zotero-rb 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4766ba9e6a279552e06f893d7a30c0689ada6c8166dbf59a1a8eaeaf56189887
-  data.tar.gz: 4f37812a884e8079d1ff2643a0e21a40f05f487e9261bc5fb902959a16c39d6c
+  metadata.gz: 6480cd849dc46519c7a122f454e93f34befae86b340703dedc69781c59cb9a37
+  data.tar.gz: c9890904401b2589eef07693b5e42fb798bbf81779fc2449e941cd6a1a33110b
 SHA512:
-  metadata.gz: d03e2f9b7eb2323eca3a6e896a22d295b80e999037c7a345c5e10bc60cc10fe79218b6f801b71ad89dffb657aa63f023047e7518cd5cc2c7105ddfbc763b32fa
-  data.tar.gz: 25b58f33822bcae33b0f65a6090e744fc0f1f8198bc16ba23b87cfcc2703c679b7dc9f76d9139e1a257661265dc2bf907052130efdff1158975e15322621d0fd
+  metadata.gz: 5c15301b1d99903ee690fca6dc77de020122fdf82ea46fe156238e16ef792b44e0ab6847548ff6bf9a563264a255719fb1caada748adbf9d8c0e1b0f35aaa4a7
+  data.tar.gz: a25a0ad4d3e46e8577380c653fc25f472232c5d631451135f5c3acba468d8970f9cf21f4789b9ad691a1f2b2a5e4ca8651d06cef1f7e7081d42f619da404b2f5

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5](https://github.com/andrewhwaller/zotero-rb/compare/v0.1.4...v0.1.5) (2025-09-11)
+
+
+### Bug Fixes
+
+* correct test expectations for refactored parameter signature ([eaad0bb](https://github.com/andrewhwaller/zotero-rb/commit/eaad0bbd0ce87cbe640b4ca7190759170ac11494))
+* Correct test method calls to match API signatures ([76dd63e](https://github.com/andrewhwaller/zotero-rb/commit/76dd63e4d6e36c18629c377d7084efc8c6159560))
+
+## [1.0.0](https://github.com/andrewhwaller/zotero-rb/compare/v0.1.2...v1.0.0) (2025-09-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* Internal HTTP implementation migrated from HTTParty to Net::HTTP
+
+### Features
+
+* replace HTTParty with Net::HTTP to eliminate dependencies ([f1af7cc](https://github.com/andrewhwaller/zotero-rb/commit/f1af7ccd27cf401bd963062763b701f2b32ea923))
+
+
+### Bug Fixes
+
+* avoid Digest mocking to resolve CI RSpec environment issues ([94adc4a](https://github.com/andrewhwaller/zotero-rb/commit/94adc4a7edd6fd8362c9794f1b1826fd8dda5ec9))
+* move digest require to top level for test compatibility ([c88a64b](https://github.com/andrewhwaller/zotero-rb/commit/c88a64b8972018b9e01682cd9f405f0d3b5f4fec))
+
 ## [0.1.2](https://github.com/andrewhwaller/zotero-rb/compare/v0.1.1...v0.1.2) (2025-09-04)
 
 

data/README.md

@@ -5,7 +5,7 @@
 
 A comprehensive Ruby client for the [Zotero Web API v3](https://www.zotero.org/support/dev/web_api/v3/start).
 
-NOTE: This gem is experimental and has not been fully tested with real data. So far, the gem has been set up to cover Zotero's web API documentation as much as possible, but testing is still ongoing. Do not use this gem for production applications without exercising due caution.
+NOTE: This gem is experimental and has not been fully tested with real data. So far, the gem has been set up to cover Zotero's web API documentation as much as possible, but testing is still ongoing. Do not use this gem for production applications without exercising due caution. Having said that, if you come across something that doesn't work, open up an issue or even a PR and I'd be happy to get a fix going.
 
 ## Installation
 

data/lib/zotero/client.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
-require "httparty"
+require "net/http"
+require "uri"
+require "json"
+require "cgi"
 require_relative "item_types"
 require_relative "fields"
 require_relative "file_upload"
 require_relative "http_errors"
 require_relative "syncing"
+require_relative "http_config"
+require_relative "http_connection"
+require_relative "network_errors"
 
 module Zotero
   # The main HTTP client for interacting with the Zotero Web API v3.
@@ -15,65 +21,25 @@ module Zotero
   #   client = Zotero::Client.new(api_key: 'your-api-key-here')
   #   library = client.user_library(12345)
   #
+  # rubocop:disable Metrics/ClassLength
   class Client
-    include HTTParty
     include ItemTypes
     include Fields
     include FileUpload
     include HTTPErrors
     include Syncing
+    include NetworkErrors
 
-    base_uri "https://api.zotero.org"
+    BASE_URI = "https://api.zotero.org"
 
     # Initialize a new Zotero API client.
     #
     # @param api_key [String] Your Zotero API key from https://www.zotero.org/settings/keys
+    # @raise [ArgumentError] if api_key is nil or empty
     def initialize(api_key:)
       @api_key = api_key
     end
 
-    def get(path, params: {})
-      response = self.class.get(path,
-                                headers: auth_headers.merge(default_headers),
-                                query: params)
-      handle_response(response, params[:format])
-    end
-
-    def post(path, data:, version: nil, write_token: nil, params: {})
-      headers = build_write_headers(version: version, write_token: write_token)
-      response = self.class.post(path,
-                                 headers: headers,
-                                 body: data,
-                                 query: params)
-      handle_write_response(response)
-    end
-
-    def patch(path, data:, version: nil, params: {})
-      headers = build_write_headers(version: version)
-      response = self.class.patch(path,
-                                  headers: headers,
-                                  body: data,
-                                  query: params)
-      handle_write_response(response)
-    end
-
-    def put(path, data:, version: nil, params: {})
-      headers = build_write_headers(version: version)
-      response = self.class.put(path,
-                                headers: headers,
-                                body: data,
-                                query: params)
-      handle_write_response(response)
-    end
-
-    def delete(path, version: nil, params: {})
-      headers = build_write_headers(version: version)
-      response = self.class.delete(path,
-                                   headers: headers,
-                                   query: params)
-      handle_write_response(response)
-    end
-
     # Get a Library instance for a specific user.
     #
     # @param user_id [Integer, String] The Zotero user ID
@@ -90,9 +56,46 @@ module Zotero
       Library.new(client: self, type: :group, id: group_id)
     end
 
-    private
+    # Make a GET request to the Zotero API.
+    # This is the main public interface for read operations.
+    #
+    # @param path [String] The API endpoint path
+    # @param params [Hash] Query parameters for the request
+    # @return [Array, Hash] The parsed response data
+    def make_get_request(path, params: {})
+      headers = auth_headers.merge(default_headers)
+      response = http_request(:get, path, headers: headers, params: params)
+      handle_response(response, params[:format])
+    end
 
-    attr_reader :api_key
+    # Make a write request (POST, PATCH, PUT, DELETE) to the Zotero API.
+    # This is the main public interface for write operations.
+    #
+    # @param method [Symbol] The HTTP method (:post, :patch, :put, :delete)
+    # @param path [String] The API endpoint path
+    # @param data [Hash, Array] Optional request body data
+    # @param options [Hash] Write options (version: Integer, write_token: String)
+    # @param params [Hash] Query parameters for the request
+    # @return [Hash, Boolean] The parsed response data or success status
+    def make_write_request(method, path, data: nil, options: {}, params: {})
+      headers = build_write_headers(version: options[:version], write_token: options[:write_token])
+      response = http_request(method, path, headers: headers, body: data, params: params)
+      handle_write_response(response)
+    end
+
+    protected
+
+    def http_request(method, path, **options)
+      request_options = build_request_options(options)
+      uri = build_uri(path, request_options[:params])
+
+      handle_network_errors do
+        connection = HTTPConnection.new(uri)
+        request = build_request(method, uri, request_options[:headers], request_options[:body], request_options)
+
+        connection.request(request)
+      end
+    end
 
     def auth_headers
       { "Zotero-API-Key" => api_key }
@@ -111,15 +114,15 @@ module Zotero
     end
 
     def handle_response(response, format = nil)
-      return parse_response_body(response, format) if response.code.between?(200, 299)
+      return parse_response_body(response, format) if response.code.to_i.between?(200, 299)
 
       raise_error_for_status(response)
     end
 
     def handle_write_response(response)
-      case response.code
+      case response.code.to_i
       when 200
-        response.parsed_response
+        parse_json_response(response)
       when 204
         true
       else
@@ -127,13 +130,85 @@ module Zotero
       end
     end
 
+    private
+
+    attr_reader :api_key
+
+    def build_request_options(options)
+      {
+        headers: options[:headers] || {},
+        body: options[:body],
+        params: options[:params] || {},
+        multipart: options[:multipart],
+        format: options[:format]
+      }
+    end
+
+    def build_uri(path, params = {})
+      base = path.start_with?("http") ? path : "#{BASE_URI}#{path}"
+      uri = URI(base)
+
+      unless params.empty?
+        query_params = params.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join("&")
+        uri.query = uri.query ? "#{uri.query}&#{query_params}" : query_params
+      end
+
+      uri
+    end
+
+    def build_request(method, uri, headers, body, request_options)
+      request = create_request(method, uri)
+      set_headers(request, headers)
+      set_request_body(request, method, body, headers, request_options) if body
+      request
+    end
+
+    def create_request(method, uri)
+      request_class = case method
+                      when :get then Net::HTTP::Get
+                      when :post then Net::HTTP::Post
+                      when :put then Net::HTTP::Put
+                      when :patch then Net::HTTP::Patch
+                      when :delete then Net::HTTP::Delete
+                      else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      request_class.new(uri)
+    end
+
+    def set_headers(request, headers)
+      headers.each { |key, value| request[key] = value }
+    end
+
+    def set_request_body(request, method, body, headers, request_options)
+      return unless %i[post put patch].include?(method)
+
+      if request_options[:multipart]
+        request.set_form(body, "multipart/form-data")
+      elsif headers["Content-Type"] == "application/x-www-form-urlencoded"
+        request.set_form_data(body)
+      else
+        request.body = body.is_a?(String) ? body : JSON.generate(body)
+        request["Content-Type"] = "application/json" unless headers["Content-Type"]
+      end
+    end
+
     def parse_response_body(response, format)
       case format&.to_s
       when "json", nil
-        response.parsed_response
+        parse_json_response(response)
       else
         response.body
       end
     end
+
+    def parse_json_response(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/zotero/fields.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Zotero
-  # Field discovery methods
+  # Field discovery methods for Zotero items and creators
   module Fields
+    # Get all available item fields.
+    #
+    # @param locale [String] Optional locale for localized field names (e.g. 'en-US', 'fr-FR')
+    # @return [Array<Hash>] Array of field definitions with field names and localized labels
     def item_fields(locale: nil)
-      get("/itemFields", params: build_locale_params(locale))
+      params = build_locale_params(locale)
+      make_get_request("/itemFields", params: params)
     end
 
+    # Get all available creator fields.
+    #
+    # @param locale [String] Optional locale for localized field names (e.g. 'en-US', 'fr-FR')
+    # @return [Array<Hash>] Array of creator field definitions with field names and localized labels
     def creator_fields(locale: nil)
-      get("/creatorFields", params: build_locale_params(locale))
+      params = build_locale_params(locale)
+      make_get_request("/creatorFields", params: params)
     end
 
     private

data/lib/zotero/{library_file_operations.rb → file_attachments.rb}

@@ -1,20 +1,42 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Zotero
-  # File upload operations for library items
-  module LibraryFileOperations
+  # File attachment operations for library items
+  module FileAttachments
+    # Create a new attachment item in the library.
+    #
+    # @param attachment_data [Hash] The attachment data including itemType, contentType, etc.
+    # @param version [Integer] Optional version for conditional requests
+    # @param write_token [String] Optional write token for batch operations
+    # @return [Hash] The API response with created attachment
     def create_attachment(attachment_data, version: nil, write_token: nil)
       create_single("items", attachment_data, version: version, write_token: write_token)
     end
 
+    # Get file information for an attachment item.
+    #
+    # @param item_key [String] The attachment item key
+    # @return [Hash] File information including filename, md5, mtime
     def get_file_info(item_key)
-      @client.get("#{@base_path}/items/#{item_key}/file")
+      @client.make_get_request("#{@base_path}/items/#{item_key}/file")
     end
 
+    # Upload a file to an attachment item.
+    #
+    # @param item_key [String] The attachment item key
+    # @param file_path [String] Local path to the file to upload
+    # @return [Boolean] Success status
     def upload_file(item_key, file_path)
       perform_file_upload(item_key, file_path, existing_file: false)
     end
 
+    # Update the file content of an existing attachment.
+    #
+    # @param item_key [String] The attachment item key
+    # @param file_path [String] Local path to the new file
+    # @return [Boolean] Success status
     def update_file(item_key, file_path)
       perform_file_upload(item_key, file_path, existing_file: true)
     end
@@ -36,8 +58,6 @@ module Zotero
     end
 
     def extract_file_metadata(file_path)
-      require "digest"
-
       {
         filename: File.basename(file_path),
         md5: Digest::MD5.file(file_path).hexdigest,

data/lib/zotero/file_upload.rb

@@ -9,18 +9,19 @@ module Zotero
       headers["If-Match"] = if_match if if_match
       headers["If-None-Match"] = if_none_match if if_none_match
 
-      response = self.class.post(path, headers: headers, body: form_data, query: params)
+      response = http_request(:post, path, headers: headers, body: form_data, params: params)
       handle_response(response)
     end
 
     def external_post(url, multipart_data:)
-      response = self.class.post(url, body: multipart_data, multipart: true, format: :plain)
+      response = http_request(:post, url, body: multipart_data, multipart: true, format: :plain)
 
-      case response.code
+      code = response.code.to_i
+      case code
       when 200..299
         response.body
       else
-        raise Error, "External upload failed: HTTP #{response.code} - #{response.message}"
+        raise Error, "External upload failed: HTTP #{code} - #{response.message}"
       end
     end
 

data/lib/zotero/fulltext.rb

@@ -1,17 +1,34 @@
 # frozen_string_literal: true
 
 module Zotero
+  # Fulltext search and content methods
   module Fulltext
+    # Get fulltext content that has been modified since a given version.
+    #
+    # @param since [Integer] Version number to get changes since
+    # @return [Hash] Object mapping item keys to version numbers
     def fulltext_since(since:)
-      @client.get("#{@base_path}/fulltext", params: { since: since })
+      params = { since: since }
+      @client.make_get_request("#{@base_path}/fulltext", params: params)
     end
 
+    # Get the fulltext content for a specific item.
+    #
+    # @param item_key [String] The item key to get fulltext for
+    # @return [Hash] Fulltext content data including content, indexedChars, and totalChars
     def item_fulltext(item_key)
-      @client.get("#{@base_path}/items/#{item_key}/fulltext")
+      @client.make_get_request("#{@base_path}/items/#{item_key}/fulltext")
     end
 
+    # Set the fulltext content for a specific item.
+    #
+    # @param item_key [String] The item key to set fulltext for
+    # @param content_data [Hash] Fulltext content data with content, indexedChars, totalChars
+    # @param version [Integer] Optional version for optimistic concurrency control
+    # @return [Boolean] Success status
     def set_item_fulltext(item_key, content_data, version: nil)
-      @client.put("#{@base_path}/items/#{item_key}/fulltext", data: content_data, version: version)
+      @client.make_write_request(:put, "#{@base_path}/items/#{item_key}/fulltext", data: content_data,
+                                                                                   options: { version: version })
     end
   end
 end

data/lib/zotero/http_config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Zotero
+  # Configuration for HTTP requests
+  class HTTPConfig
+    attr_accessor :open_timeout, :read_timeout, :verify_ssl
+
+    def initialize(open_timeout: 30, read_timeout: 60, verify_ssl: true)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @verify_ssl = verify_ssl
+    end
+
+    def self.default
+      @default ||= new
+    end
+
+    def self.configure
+      yield(default) if block_given?
+      default
+    end
+  end
+end

data/lib/zotero/http_connection.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+
+module Zotero
+  # Manages HTTP connections with proper SSL configuration and timeouts
+  class HTTPConnection
+    DEFAULT_OPEN_TIMEOUT = 30
+    DEFAULT_READ_TIMEOUT = 60
+
+    def initialize(uri, config = nil)
+      @uri = uri
+      @config = config || HTTPConfig.default
+      @http = build_connection
+    end
+
+    def request(net_request)
+      configure_connection unless @configured
+      @http.request(net_request)
+    end
+
+    private
+
+    attr_reader :uri, :config, :http
+
+    def build_connection
+      Net::HTTP.new(@uri.host, @uri.port)
+    end
+
+    def configure_connection
+      configure_ssl if @uri.scheme == "https"
+      configure_timeouts
+      @configured = true
+    end
+
+    def configure_ssl
+      @http.use_ssl = true
+      @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      @http.ca_file = OpenSSL::X509::DEFAULT_CERT_FILE
+    end
+
+    def configure_timeouts
+      @http.open_timeout = @config.open_timeout
+      @http.read_timeout = @config.read_timeout
+    end
+  end
+end

data/lib/zotero/http_errors.rb

@@ -4,7 +4,8 @@ module Zotero
   # HTTP error handling methods
   module HTTPErrors
     def raise_error_for_status(response)
-      case response.code
+      code = response.code.to_i
+      case code
       when 400..428 then raise_client_error(response)
       when 429 then raise_rate_limit_error(response)
       else raise_server_or_unknown_error(response)
@@ -12,10 +13,11 @@ module Zotero
     end
 
     def raise_client_error(response)
-      case response.code
+      code = response.code.to_i
+      case code
       when 400, 413 then raise BadRequestError, "Bad request: #{response.body}"
       when 401, 403 then raise AuthenticationError, "Authentication failed - check your API key"
-      when 404 then raise NotFoundError, "Resource not found: #{response.request.path}"
+      when 404 then raise NotFoundError, "Resource not found"
       when 409 then raise ConflictError, "Conflict: #{response.body}"
       when 412 then raise PreconditionFailedError, "Precondition failed: #{response.body}"
       when 428 then raise PreconditionRequiredError, "Precondition required: #{response.body}"
@@ -23,8 +25,9 @@ module Zotero
     end
 
     def raise_rate_limit_error(response)
-      backoff = response.headers["backoff"]&.to_i
-      retry_after = response.headers["retry-after"]&.to_i
+      headers = response.to_hash.transform_values(&:first)
+      backoff = headers["backoff"]&.to_i
+      retry_after = headers["retry-after"]&.to_i
       message = "Rate limited."
       message += " Backoff: #{backoff}s" if backoff
       message += " Retry after: #{retry_after}s" if retry_after
@@ -32,11 +35,12 @@ module Zotero
     end
 
     def raise_server_or_unknown_error(response)
-      case response.code
+      code = response.code.to_i
+      case code
       when 500..599
-        raise ServerError, "Server error: HTTP #{response.code} - #{response.message}"
+        raise ServerError, "Server error: HTTP #{code} - #{response.message}"
       else
-        raise Error, "Unexpected response: HTTP #{response.code} - #{response.message}"
+        raise Error, "Unexpected response: HTTP #{code} - #{response.message}"
       end
     end
   end

data/lib/zotero/item_types.rb

@@ -3,22 +3,42 @@
 module Zotero
   # Item type discovery and template methods
   module ItemTypes
+    # Get all available item types.
+    #
+    # @param locale [String] Optional locale for localized type names (e.g. 'en-US', 'fr-FR')
+    # @return [Array<Hash>] Array of item type definitions
     def item_types(locale: nil)
-      get("/itemTypes", params: build_locale_params(locale))
+      params = build_locale_params(locale)
+      make_get_request("/itemTypes", params: params)
     end
 
+    # Get all fields available for a specific item type.
+    #
+    # @param item_type [String] The item type name (e.g. 'book', 'journalArticle')
+    # @param locale [String] Optional locale for localized field names
+    # @return [Array<Hash>] Array of field definitions for the item type
     def item_type_fields(item_type, locale: nil)
       params = { itemType: item_type }
       params.merge!(build_locale_params(locale))
-      get("/itemTypeFields", params: params)
+      make_get_request("/itemTypeFields", params: params)
     end
 
+    # Get all creator types available for a specific item type.
+    #
+    # @param item_type [String] The item type name (e.g. 'book', 'journalArticle')
+    # @return [Array<Hash>] Array of creator type definitions for the item type
     def item_type_creator_types(item_type)
-      get("/itemTypeCreatorTypes", params: { itemType: item_type })
+      params = { itemType: item_type }
+      make_get_request("/itemTypeCreatorTypes", params: params)
     end
 
+    # Get a new item template for a specific item type.
+    #
+    # @param item_type [String] The item type name (e.g. 'book', 'journalArticle')
+    # @return [Hash] Template object with empty fields for the item type
     def new_item_template(item_type)
-      get("/items/new", params: { itemType: item_type })
+      params = { itemType: item_type }
+      make_get_request("/items/new", params: params)
     end
 
     private

data/lib/zotero/library.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "library_file_operations"
+require_relative "file_attachments"
 require_relative "fulltext"
 require_relative "syncing"
 
@@ -15,8 +15,7 @@ module Zotero
   #   collections = library.collections
   #
   class Library
-    # TODO: rename this module, LibraryFileOperations sounds weird
-    include LibraryFileOperations
+    include FileAttachments
     include Fulltext
     include Syncing
 
@@ -39,7 +38,7 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Collections data from the API
     def collections(**params)
-      @client.get("#{@base_path}/collections", params: params)
+      @client.make_get_request("#{@base_path}/collections", params: params)
     end
 
     # Get items in this library.
@@ -47,15 +46,23 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Items data from the API
     def items(**params)
-      @client.get("#{@base_path}/items", params: params)
+      @client.make_get_request("#{@base_path}/items", params: params)
     end
 
+    # Get saved searches in this library.
+    #
+    # @param params [Hash] Query parameters for the request
+    # @return [Array, Hash] Saved searches data from the API
     def searches(**params)
-      @client.get("#{@base_path}/searches", params: params)
+      @client.make_get_request("#{@base_path}/searches", params: params)
     end
 
+    # Get tags in this library.
+    #
+    # @param params [Hash] Query parameters for the request
+    # @return [Array, Hash] Tags data from the API
     def tags(**params)
-      @client.get("#{@base_path}/tags", params: params)
+      @client.make_get_request("#{@base_path}/tags", params: params)
     end
 
     # Create a new item in this library.
@@ -68,41 +75,95 @@ module Zotero
       create_single("items", item_data, version: version, write_token: write_token)
     end
 
+    # Create multiple items in this library.
+    #
+    # @param items_array [Array<Hash>] Array of item data objects
+    # @param version [Integer] Optional version for conditional requests
+    # @param write_token [String] Optional write token for batch operations
+    # @return [Hash] The API response with created items
     def create_items(items_array, version: nil, write_token: nil)
       create_multiple("items", items_array, version: version, write_token: write_token)
     end
 
+    # Update an existing item in this library.
+    #
+    # @param item_key [String] The item key to update
+    # @param item_data [Hash] The updated item data
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Hash] The API response
     def update_item(item_key, item_data, version: nil)
-      @client.patch("#{@base_path}/items/#{item_key}", data: item_data, version: version)
+      @client.make_write_request(:patch, "#{@base_path}/items/#{item_key}", data: item_data,
+                                                                            options: { version: version })
     end
 
+    # Delete an item from this library.
+    #
+    # @param item_key [String] The item key to delete
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Boolean] Success status
     def delete_item(item_key, version: nil)
-      @client.delete("#{@base_path}/items/#{item_key}", version: version)
+      @client.make_write_request(:delete, "#{@base_path}/items/#{item_key}", options: { version: version })
     end
 
+    # Delete multiple items from this library.
+    #
+    # @param item_keys [Array<String>] Array of item keys to delete
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Boolean] Success status
     def delete_items(item_keys, version: nil)
-      @client.delete("#{@base_path}/items", version: version, params: { itemKey: item_keys.join(",") })
+      @client.make_write_request(:delete, "#{@base_path}/items", options: { version: version },
+                                                                 params: { itemKey: item_keys.join(",") })
     end
 
+    # Create a new collection in this library.
+    #
+    # @param collection_data [Hash] The collection data
+    # @param version [Integer] Optional version for conditional requests
+    # @param write_token [String] Optional write token for batch operations
+    # @return [Hash] The API response
     def create_collection(collection_data, version: nil, write_token: nil)
       create_single("collections", collection_data, version: version, write_token: write_token)
     end
 
+    # Create multiple collections in this library.
+    #
+    # @param collections_array [Array<Hash>] Array of collection data objects
+    # @param version [Integer] Optional version for conditional requests
+    # @param write_token [String] Optional write token for batch operations
+    # @return [Hash] The API response with created collections
     def create_collections(collections_array, version: nil, write_token: nil)
       create_multiple("collections", collections_array, version: version, write_token: write_token)
     end
 
+    # Update an existing collection in this library.
+    #
+    # @param collection_key [String] The collection key to update
+    # @param collection_data [Hash] The updated collection data
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Hash] The API response
     def update_collection(collection_key, collection_data, version: nil)
-      @client.patch("#{@base_path}/collections/#{collection_key}", data: collection_data, version: version)
+      @client.make_write_request(:patch, "#{@base_path}/collections/#{collection_key}", data: collection_data,
+                                                                                        options: { version: version })
     end
 
+    # Delete a collection from this library.
+    #
+    # @param collection_key [String] The collection key to delete
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Boolean] Success status
     def delete_collection(collection_key, version: nil)
-      @client.delete("#{@base_path}/collections/#{collection_key}", version: version)
+      @client.make_write_request(:delete, "#{@base_path}/collections/#{collection_key}", options: { version: version })
     end
 
+    # Delete multiple collections from this library.
+    #
+    # @param collection_keys [Array<String>] Array of collection keys to delete
+    # @param version [Integer] Version for optimistic concurrency control
+    # @return [Boolean] Success status
     def delete_collections(collection_keys, version: nil)
-      @client.delete("#{@base_path}/collections", version: version,
-                                                  params: { collectionKey: collection_keys.join(",") })
+      @client.make_write_request(:delete, "#{@base_path}/collections",
+                                 options: { version: version },
+                                 params: { collectionKey: collection_keys.join(",") })
     end
 
     private
@@ -110,11 +171,15 @@ module Zotero
     attr_reader :client, :type, :id, :base_path
 
     def create_single(resource, data, version: nil, write_token: nil)
-      @client.post("#{@base_path}/#{resource}", data: [data], version: version, write_token: write_token)
+      @client.make_write_request(:post, "#{@base_path}/#{resource}",
+                                 data: [data],
+                                 options: { version: version, write_token: write_token })
     end
 
     def create_multiple(resource, data_array, version: nil, write_token: nil)
-      @client.post("#{@base_path}/#{resource}", data: data_array, version: version, write_token: write_token)
+      @client.make_write_request(:post, "#{@base_path}/#{resource}",
+                                 data: data_array,
+                                 options: { version: version, write_token: write_token })
     end
 
     def validate_type(type)

data/lib/zotero/network_errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "socket"
+require "openssl"
+
+module Zotero
+  # Handles network errors and translates them to appropriate Zotero exceptions
+  module NetworkErrors
+    ERROR_MESSAGES = {
+      Errno::ECONNREFUSED => "Connection refused - server may be down",
+      Errno::EHOSTUNREACH => "Host unreachable - check network connectivity",
+      Errno::ENETUNREACH => "Host unreachable - check network connectivity",
+      SocketError => "DNS resolution failed - check hostname",
+      Net::OpenTimeout => "Connection timeout - server took too long to respond",
+      Net::ReadTimeout => "Read timeout - server response was too slow",
+      OpenSSL::SSL::SSLError => "SSL error - certificate verification failed",
+      Timeout::Error => "Request timeout"
+    }.freeze
+
+    def handle_network_errors
+      yield
+    rescue *network_error_classes => e
+      raise translate_network_error(e)
+    end
+
+    private
+
+    def network_error_classes
+      [
+        Errno::ECONNREFUSED,
+        Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH,
+        SocketError,
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        OpenSSL::SSL::SSLError,
+        Timeout::Error
+      ]
+    end
+
+    def translate_network_error(error)
+      message = error_message_for(error)
+      Error.new("#{message} (#{error.class})")
+    end
+
+    def error_message_for(error)
+      ERROR_MESSAGES.fetch(error.class) { "Network error: #{error.message}" }
+    end
+  end
+end

data/lib/zotero/syncing.rb

@@ -1,19 +1,40 @@
 # frozen_string_literal: true
 
 module Zotero
+  # Syncing and API key verification methods
   module Syncing
+    # Verify that the current API key is valid.
+    #
+    # @return [Hash] API key information including userID and username
     def verify_api_key
-      @client ? @client.get("/keys/current") : get("/keys/current")
+      if @client
+        @client.make_get_request("/keys/current")
+      else
+        make_get_request("/keys/current")
+      end
     end
 
+    # Get groups for a specific user.
+    #
+    # @param user_id [Integer, String] The user ID to get groups for
+    # @param format [String] Response format ('versions' or 'json')
+    # @return [Hash, Array] Groups data in the requested format
     def user_groups(user_id, format: "versions")
-      client = @client || self
-      client.get("/users/#{user_id}/groups", params: { format: format })
+      params = { format: format }
+      if @client
+        @client.make_get_request("/users/#{user_id}/groups", params: params)
+      else
+        make_get_request("/users/#{user_id}/groups", params: params)
+      end
     end
 
+    # Get items that have been deleted from this library.
+    #
+    # @param since [Integer] Optional version to get deletions since
+    # @return [Hash] Object with deleted collections and items arrays
     def deleted_items(since: nil)
       params = since ? { since: since } : {}
-      @client.get("#{@base_path}/deleted", params: params)
+      @client.make_get_request("#{@base_path}/deleted", params: params)
     end
   end
 end

data/lib/zotero/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zotero
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,42 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zotero-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Andrew Waller
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: csv
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: httparty
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.21.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.21.0
+dependencies: []
 description: A feature-complete Ruby client for the Zotero Web API v3, providing full
   CRUD operations for items, collections, tags, and searches, plus file uploads, fulltext
   content access, and library synchronization. Built with a modular architecture and
@@ -60,12 +32,15 @@ files:
 - lib/zotero/client.rb
 - lib/zotero/error.rb
 - lib/zotero/fields.rb
+- lib/zotero/file_attachments.rb
 - lib/zotero/file_upload.rb
 - lib/zotero/fulltext.rb
+- lib/zotero/http_config.rb
+- lib/zotero/http_connection.rb
 - lib/zotero/http_errors.rb
 - lib/zotero/item_types.rb
 - lib/zotero/library.rb
-- lib/zotero/library_file_operations.rb
+- lib/zotero/network_errors.rb
 - lib/zotero/syncing.rb
 - lib/zotero/version.rb
 - sig/zotero/rb.rbs
@@ -95,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A comprehensive Ruby client for the Zotero Web API v3
 test_files: []