zotero-rb 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6480cd849dc46519c7a122f454e93f34befae86b340703dedc69781c59cb9a37
-  data.tar.gz: c9890904401b2589eef07693b5e42fb798bbf81779fc2449e941cd6a1a33110b
+  metadata.gz: ed5e1bc966a90e528cdcb874afebc4e6fb0b7941f0d1b641f25c686660b42a82
+  data.tar.gz: 07becabbc5d55a481b7d3f9945f671ec7ee183ee72cbbd8b84410f065679152e
 SHA512:
-  metadata.gz: 5c15301b1d99903ee690fca6dc77de020122fdf82ea46fe156238e16ef792b44e0ab6847548ff6bf9a563264a255719fb1caada748adbf9d8c0e1b0f35aaa4a7
-  data.tar.gz: a25a0ad4d3e46e8577380c653fc25f472232c5d631451135f5c3acba468d8970f9cf21f4789b9ad691a1f2b2a5e4ca8651d06cef1f7e7081d42f619da404b2f5
+  metadata.gz: d57c1a5cbf941b10c9871352715cf2f9e04859a9c32cc6dfb34c911797d5c419ee74bfb7a1e2c1bc7ce64283636155867867142c094eaea85abacc2606d84890
+  data.tar.gz: 449b2c7e9bede8968cf0a99a7d270e3796a09390aefd3ea4228bd14c29967113bf2d5aa01b97d497fc168b335ebf71e11cc9682a42f30ef6ba9afddf9be49615

data/lib/zotero/client.rb

@@ -63,9 +63,11 @@ module Zotero
     # @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])
+      with_retry do
+        headers = auth_headers.merge(default_headers)
+        response = http_request(:get, path, headers: headers, params: params)
+        handle_response(response, params[:format])
+      end
     end
 
     # Make a write request (POST, PATCH, PUT, DELETE) to the Zotero API.
@@ -78,9 +80,11 @@ module Zotero
     # @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)
+      with_retry do
+        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
     end
 
     protected
@@ -134,6 +138,29 @@ module Zotero
 
     attr_reader :api_key
 
+    def with_retry
+      config = HTTPConfig.default
+      attempts = 0
+
+      begin
+        yield
+      rescue RateLimitError => e
+        attempts += 1
+        raise unless should_retry?(config, attempts)
+
+        sleep(calculate_retry_delay(e, attempts, config))
+        retry
+      end
+    end
+
+    def should_retry?(config, attempts)
+      config.retry_on_rate_limit && attempts <= config.max_retries
+    end
+
+    def calculate_retry_delay(error, attempt, config)
+      [error.wait_time, config.base_delay * (2**(attempt - 1))].max
+    end
+
     def build_request_options(options)
       {
         headers: options[:headers] || {},
@@ -206,8 +233,8 @@ module Zotero
       return nil if response.body.nil? || response.body.empty?
 
       JSON.parse(response.body)
-    rescue JSON::ParserError
-      response.body
+    rescue JSON::ParserError => e
+      raise ParseError, "Failed to parse JSON response: #{e.message}"
     end
   end
   # rubocop:enable Metrics/ClassLength

data/lib/zotero/error.rb

@@ -3,11 +3,27 @@
 module Zotero
   class Error < StandardError; end
   class AuthenticationError < Error; end
-  class RateLimitError < Error; end
+
+  # Raised when the API rate limit is exceeded
+  class RateLimitError < Error
+    attr_reader :retry_after, :backoff
+
+    def initialize(message, retry_after: nil, backoff: nil)
+      super(message)
+      @retry_after = retry_after
+      @backoff = backoff
+    end
+
+    def wait_time
+      @retry_after || @backoff || 1
+    end
+  end
+
   class NotFoundError < Error; end
   class BadRequestError < Error; end
   class ServerError < Error; end
   class ConflictError < Error; end
   class PreconditionFailedError < Error; end
   class PreconditionRequiredError < Error; end
+  class ParseError < Error; end
 end

data/lib/zotero/file_attachments.rb

@@ -70,20 +70,22 @@ module Zotero
     end
 
     def perform_external_upload(auth_response, file_path, upload_path)
-      if auth_response["url"]
-        upload_params = build_upload_params(auth_response, file_path)
-        @client.external_post(auth_response["url"], multipart_data: upload_params)
-      end
+      upload_to_storage(auth_response, file_path) if auth_response["url"]
+      register_upload_completion(auth_response, upload_path)
+    end
 
-      if auth_response["uploadKey"]
-        @client.register_upload(upload_path, upload_key: auth_response["uploadKey"])
-      else
-        true
-      end
+    def upload_to_storage(auth_response, file_path)
+      @client.external_post(auth_response["url"], multipart_data: build_upload_params(auth_response, file_path))
+    end
+
+    def register_upload_completion(auth_response, upload_path)
+      return true unless auth_response["uploadKey"]
+
+      @client.register_upload(upload_path, upload_key: auth_response["uploadKey"])
     end
 
     def build_upload_params(auth_response, file_path)
-      file_data = File.open(file_path, "rb")
+      file_data = File.binread(file_path)
 
       if auth_response["params"]
         auth_response["params"].merge("file" => file_data)

data/lib/zotero/http_config.rb

@@ -1,14 +1,28 @@
 # frozen_string_literal: true
 
 module Zotero
-  # Configuration for HTTP requests
+  # Configuration for HTTP requests and retry behavior
   class HTTPConfig
-    attr_accessor :open_timeout, :read_timeout, :verify_ssl
+    attr_accessor :open_timeout, :read_timeout, :verify_ssl,
+                  :retry_on_rate_limit, :max_retries, :base_delay
 
-    def initialize(open_timeout: 30, read_timeout: 60, verify_ssl: true)
-      @open_timeout = open_timeout
-      @read_timeout = read_timeout
-      @verify_ssl = verify_ssl
+    DEFAULTS = {
+      open_timeout: 30,
+      read_timeout: 60,
+      verify_ssl: true,
+      retry_on_rate_limit: true,
+      max_retries: 3,
+      base_delay: 1.0
+    }.freeze
+
+    def initialize(**options)
+      config = DEFAULTS.merge(options)
+      @open_timeout = config[:open_timeout]
+      @read_timeout = config[:read_timeout]
+      @verify_ssl = config[:verify_ssl]
+      @retry_on_rate_limit = config[:retry_on_rate_limit]
+      @max_retries = config[:max_retries]
+      @base_delay = config[:base_delay]
     end
 
     def self.default

data/lib/zotero/http_errors.rb

@@ -14,16 +14,23 @@ module Zotero
 
     def raise_client_error(response)
       code = response.code.to_i
+      detail = error_detail(response)
+
       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"
-      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}"
+      when 400, 413 then raise BadRequestError, "Bad request: #{detail}"
+      when 401, 403 then raise AuthenticationError, "Authentication failed: #{detail}"
+      when 404 then raise NotFoundError, "Resource not found: #{detail}"
+      when 409 then raise ConflictError, "Conflict: #{detail}"
+      when 412 then raise PreconditionFailedError, "Precondition failed: #{detail}"
+      when 428 then raise PreconditionRequiredError, "Precondition required: #{detail}"
       end
     end
 
+    def error_detail(response)
+      body = response.body.to_s.strip
+      body.empty? ? "(no details)" : body
+    end
+
     def raise_rate_limit_error(response)
       headers = response.to_hash.transform_values(&:first)
       backoff = headers["backoff"]&.to_i
@@ -31,7 +38,7 @@ module Zotero
       message = "Rate limited."
       message += " Backoff: #{backoff}s" if backoff
       message += " Retry after: #{retry_after}s" if retry_after
-      raise RateLimitError, message
+      raise RateLimitError.new(message, retry_after: retry_after, backoff: backoff)
     end
 
     def raise_server_or_unknown_error(response)

data/lib/zotero/library.rb

@@ -26,10 +26,11 @@ module Zotero
     # @param client [Client] The Zotero client instance
     # @param type [String, Symbol] The library type (:user or :group)
     # @param id [Integer, String] The library ID (user ID or group ID)
+    # @raise [ArgumentError] if type is invalid or id is not a positive integer
     def initialize(client:, type:, id:)
       @client = client
       @type = validate_type(type)
-      @id = id
+      @id = validate_id(id)
       @base_path = "/#{@type}s/#{@id}"
     end
 
@@ -38,7 +39,7 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Collections data from the API
     def collections(**params)
-      @client.make_get_request("#{@base_path}/collections", params: params)
+      client.make_get_request("#{base_path}/collections", params: params)
     end
 
     # Get items in this library.
@@ -46,7 +47,7 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Items data from the API
     def items(**params)
-      @client.make_get_request("#{@base_path}/items", params: params)
+      client.make_get_request("#{base_path}/items", params: params)
     end
 
     # Get saved searches in this library.
@@ -54,7 +55,7 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Saved searches data from the API
     def searches(**params)
-      @client.make_get_request("#{@base_path}/searches", params: params)
+      client.make_get_request("#{base_path}/searches", params: params)
     end
 
     # Get tags in this library.
@@ -62,7 +63,7 @@ module Zotero
     # @param params [Hash] Query parameters for the request
     # @return [Array, Hash] Tags data from the API
     def tags(**params)
-      @client.make_get_request("#{@base_path}/tags", params: params)
+      client.make_get_request("#{base_path}/tags", params: params)
     end
 
     # Create a new item in this library.
@@ -92,8 +93,8 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Hash] The API response
     def update_item(item_key, item_data, version: nil)
-      @client.make_write_request(:patch, "#{@base_path}/items/#{item_key}", data: item_data,
-                                                                            options: { 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.
@@ -102,7 +103,7 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Boolean] Success status
     def delete_item(item_key, version: nil)
-      @client.make_write_request(:delete, "#{@base_path}/items/#{item_key}", options: { version: version })
+      client.make_write_request(:delete, "#{base_path}/items/#{item_key}", options: { version: version })
     end
 
     # Delete multiple items from this library.
@@ -111,8 +112,8 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Boolean] Success status
     def delete_items(item_keys, version: nil)
-      @client.make_write_request(:delete, "#{@base_path}/items", options: { 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.
@@ -142,8 +143,8 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Hash] The API response
     def update_collection(collection_key, collection_data, version: nil)
-      @client.make_write_request(:patch, "#{@base_path}/collections/#{collection_key}", data: collection_data,
-                                                                                        options: { 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.
@@ -152,7 +153,7 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Boolean] Success status
     def delete_collection(collection_key, version: nil)
-      @client.make_write_request(:delete, "#{@base_path}/collections/#{collection_key}", options: { version: version })
+      client.make_write_request(:delete, "#{base_path}/collections/#{collection_key}", options: { version: version })
     end
 
     # Delete multiple collections from this library.
@@ -161,9 +162,9 @@ module Zotero
     # @param version [Integer] Version for optimistic concurrency control
     # @return [Boolean] Success status
     def delete_collections(collection_keys, version: nil)
-      @client.make_write_request(:delete, "#{@base_path}/collections",
-                                 options: { 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
@@ -171,15 +172,15 @@ module Zotero
     attr_reader :client, :type, :id, :base_path
 
     def create_single(resource, data, version: nil, write_token: nil)
-      @client.make_write_request(:post, "#{@base_path}/#{resource}",
-                                 data: [data],
-                                 options: { 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.make_write_request(:post, "#{@base_path}/#{resource}",
-                                 data: data_array,
-                                 options: { 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)
@@ -190,5 +191,12 @@ module Zotero
 
       type_str
     end
+
+    def validate_id(id)
+      id_int = Integer(id, exception: false)
+      raise ArgumentError, "Invalid library ID: #{id.inspect}. Must be a positive integer" unless id_int&.positive?
+
+      id_int
+    end
   end
 end

data/lib/zotero/syncing.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 module Zotero
-  # Syncing and API key verification methods
+  # Syncing and API key verification methods.
+  #
+  # This module can be included in both Client and Library classes.
+  # Classes including this module must implement #api_client which returns
+  # the object that responds to #make_get_request.
   module Syncing
     # Verify that the current API key is valid.
     #
     # @return [Hash] API key information including userID and username
     def verify_api_key
-      if @client
-        @client.make_get_request("/keys/current")
-      else
-        make_get_request("/keys/current")
-      end
+      api_client.make_get_request("/keys/current")
     end
 
     # Get groups for a specific user.
@@ -20,21 +20,26 @@ module Zotero
     # @param format [String] Response format ('versions' or 'json')
     # @return [Hash, Array] Groups data in the requested format
     def user_groups(user_id, format: "versions")
-      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
+      api_client.make_get_request("/users/#{user_id}/groups", params: { format: format })
     end
 
     # Get items that have been deleted from this library.
+    # Only available when included in 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.make_get_request("#{@base_path}/deleted", params: params)
+      api_client.make_get_request("#{@base_path}/deleted", params: { since: since }.compact)
+    end
+
+    private
+
+    # Returns the object that handles API requests.
+    # Override in including classes if needed.
+    #
+    # @return [Object] The API client object
+    def api_client
+      @client || self
     end
   end
 end

data/lib/zotero/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zotero-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Waller
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A comprehensive Ruby client for the Zotero Web API v3
 test_files: []