zotero-rb 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4726b345f1c3ad888f6ea08fd69fefc997527aa509972db1f0aa3c38ed6e58c6
+  data.tar.gz: a4b6623d56034130a91b8067c1927120d60731aae6d71d7855c253df2bd57aa0
+SHA512:
+  metadata.gz: fc34f7ac321a12c9cda48ca5615cbabd617f8981dea664a87aa9243e5e7d677b0b6acde40108bd2813f44e34048cafb668afaa4385dfe8ecdd27eb171782b583
+  data.tar.gz: 611cd7bc28d93c0c4365aea57e833d687d65571d147a6d14197b8cab0194defdb9f29383958aa3ff87ebbc985050d82a02c35f6111c74ed83180bb52a38f2097

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 120
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"

data/.yardopts

@@ -0,0 +1,12 @@
+--protected
+--private
+--readme README.md
+--markup markdown
+--markup-provider kramdown
+--charset utf-8
+--embed-mixins
+--hide-void-return
+lib/**/*.rb
+-
+CHANGELOG.md
+CONTRIBUTING.md

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0](https://github.com/andrewhwaller/zotero-rb/compare/v0.0.0...v0.1.0) (2025-09-04)
+
+### Added
+- Initial release of zotero-rb gem
+- Full Zotero Web API v3 client with API key authentication
+- Complete CRUD operations for items, collections, tags, and searches
+- File upload and download support
+- Fulltext content access
+- Library synchronization features
+- Metadata retrieval (item types, fields, creator types)
+- Comprehensive error handling with custom exception classes
+- Support for both user and group libraries
+- Ruby 3.2+ compatibility

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Andrew Waller
+
+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,76 @@
+# Zotero Ruby Gem
+
+[![Gem Version](https://badge.fury.io/rb/zotero-rb.svg)](https://badge.fury.io/rb/zotero-rb)
+[![CI](https://github.com/andrewhwaller/zotero-rb/actions/workflows/main.yml/badge.svg)](https://github.com/andrewhwaller/zotero-rb/actions/workflows/main.yml)
+
+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.
+
+## Installation
+
+```bash
+gem install zotero-rb
+```
+
+## Usage
+
+```ruby
+require 'zotero'
+
+# Create a client with your API key
+client = Zotero.new(api_key: 'your-api-key')
+
+# Get a library (user or group)
+library = client.user_library(12345)
+group_library = client.group_library(67890)
+
+# Work with items
+items = library.items
+new_item = library.create_item(itemType: 'book', title: 'My Book')
+library.update_item('ITEM123', { title: 'Updated Title' }, version: 150)
+library.delete_item('ITEM123', version: 151)
+
+# Work with collections
+collections = library.collections
+new_collection = library.create_collection(name: 'My Collection')
+
+# Upload files
+library.upload_file('ITEM123', '/path/to/file.pdf')
+
+# Access metadata
+item_types = client.item_types
+book_fields = client.item_type_fields('book')
+```
+
+## Authentication
+
+1. Create a new Zotero API key or use an existing one in your [Zotero settings](https://www.zotero.org/settings/security)
+2. Ensure your key has the appropriate permissions (read library, write library, etc.)
+3. Pass it to the client as shown above
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+bundle exec rubocop
+```
+
+## Releases
+
+This project uses [Release Please](https://github.com/googleapis/release-please) for automated releases:
+
+1. **Use conventional commits**: `feat: add new feature`, `fix: resolve bug`, etc.
+2. **Release Please creates PRs** automatically with version bumps and changelog updates
+3. **Merge the release PR** when ready to publish
+4. **Automatic publication** to RubyGems happens after merge
+
+### Repository Setup (for maintainers)
+
+To enable automated publishing, add this secret to the GitHub repository:
+- `RUBYGEMS_API_KEY`: Your RubyGems API token from https://rubygems.org/profile/edit
+
+## License
+
+[MIT License](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+YARD::Rake::YardocTask.new(:doc)
+
+desc "Start an interactive console"
+task :console do
+  require "bundler/setup"
+  require "irb"
+  require "zotero"
+  ARGV.clear
+  IRB.start
+end
+
+task default: %i[spec rubocop]

data/TASKS.md

@@ -0,0 +1,209 @@
+# Zotero Ruby Gem Development Tasks
+
+This document tracks the development tasks for building a Ruby gem client for the Zotero Web API v3.
+
+## Phase 1: Project Setup and Foundation
+
+### 1.1 Initialize Ruby gem structure
+- [ ] Set up basic gem skeleton with `bundle gem zotero-rb`
+- [ ] Configure gemspec with proper metadata, dependencies, and Ruby version requirements
+- [ ] Set up lib/ directory structure with main module and version file
+- [ ] Create basic executable/CLI structure if needed
+
+### 1.2 Configure development dependencies  
+- [ ] Add RSpec for testing framework
+- [ ] Add RuboCop for code linting and style enforcement
+- [ ] Add development gems: pry, byebug, yard for documentation
+- [ ] Configure .rubocop.yml with appropriate rules
+- [ ] Set up Rake tasks for common development workflows
+
+### 1.3 Set up CI/CD pipeline
+- [ ] Create GitHub Actions workflow for testing
+- [ ] Configure matrix testing across Ruby versions (3.1, 3.2, 3.3)
+- [ ] Add code coverage reporting with SimpleCov
+- [ ] Set up automated RuboCop checks in CI
+- [ ] Configure automatic gem publishing on release
+
+### 1.4 Create basic project documentation
+- [ ] Write comprehensive README with installation and basic usage
+- [ ] Create CHANGELOG.md following keepachangelog.com format
+- [ ] Add proper LICENSE file (MIT recommended)
+- [ ] Set up YARD documentation configuration
+- [ ] Create CONTRIBUTING.md with development guidelines
+
+## Phase 2: Core API Client Infrastructure
+
+### 2.1 Implement HTTP client foundation
+- [ ] Create base `Zotero::Client` class
+- [ ] Choose HTTP library (Net::HTTP, Faraday, or HTTParty) and implement adapter pattern
+- [ ] Implement request/response wrapper classes
+- [ ] Add JSON parsing and serialization
+- [ ] Create configuration class for API settings
+
+### 2.2 Add authentication support
+- [ ] Implement API key authentication via `Zotero-API-Key` header
+- [ ] Add Bearer token authentication support
+- [ ] Implement OAuth 1.0a flow for getting API keys
+- [ ] Create OAuth client for handling authorization workflow
+- [ ] Add configuration for client credentials and callback URLs
+
+### 2.3 Implement rate limiting and retries
+- [ ] Add `Backoff` header handling
+- [ ] Implement exponential backoff for rate limit responses (429)
+- [ ] Create configurable retry policy
+- [ ] Add request queuing/throttling mechanism  
+- [ ] Implement circuit breaker pattern for API failures
+
+### 2.4 Create error handling system
+- [ ] Define custom exception hierarchy (`Zotero::Error` base class)
+- [ ] Create specific exceptions for different HTTP status codes
+- [ ] Add authentication error handling (`Zotero::AuthenticationError`)
+- [ ] Implement rate limit exception (`Zotero::RateLimitError`)
+- [ ] Add validation error handling for malformed requests
+
+### 2.5 Add request/response logging
+- [ ] Implement configurable logging system
+- [ ] Add request logging with sanitized sensitive data
+- [ ] Create response logging with configurable detail levels
+- [ ] Add performance timing logs
+- [ ] Support for different log levels and custom loggers
+
+## Phase 3: Core Zotero API Features
+
+### 3.1 Implement library access
+- [ ] Create `Zotero::Library` class for library operations
+- [ ] Add user library access (`/users/<userID>`)
+- [ ] Implement group library access (`/groups/<groupID>`)
+- [ ] Add library metadata retrieval
+- [ ] Create library permissions checking
+
+### 3.2 Add items management
+- [ ] Create `Zotero::Item` model class with proper attributes
+- [ ] Implement item creation (POST) with validation
+- [ ] Add item retrieval (GET) with include parameters
+- [ ] Implement item updates (PUT/PATCH)
+- [ ] Add item deletion with proper error handling
+- [ ] Support for item versions and conditional requests
+
+### 3.3 Implement collections support
+- [ ] Create `Zotero::Collection` model class
+- [ ] Add collection CRUD operations
+- [ ] Implement nested collection handling
+- [ ] Add collection membership management for items
+- [ ] Support for collection ordering and hierarchy
+
+### 3.4 Add tags functionality
+- [ ] Create `Zotero::Tag` model class
+- [ ] Implement tag creation and management
+- [ ] Add tag filtering and searching
+- [ ] Support for colored tags
+- [ ] Implement tag assignment to items
+
+### 3.5 Implement search functionality
+- [ ] Create `Zotero::Search` class for saved searches
+- [ ] Add search query building with proper parameter encoding
+- [ ] Implement result filtering and sorting
+- [ ] Add search result pagination
+- [ ] Support for different search formats (json, keys, etc.)
+
+## Phase 4: Advanced Features
+
+### 4.1 Add file upload support
+- [ ] Implement file attachment upload workflow
+- [ ] Add support for different file types and validation
+- [ ] Create progress tracking for large file uploads
+- [ ] Implement file metadata handling
+- [ ] Add file download capabilities
+
+### 4.2 Implement syncing capabilities
+- [ ] Add support for library version checking
+- [ ] Implement incremental sync with version tracking
+- [ ] Create conflict resolution strategies
+- [ ] Add sync status reporting
+- [ ] Support for partial syncing of specific resources
+
+### 4.3 Add full-text content access
+- [ ] Implement full-text content retrieval for items
+- [ ] Add full-text search capabilities
+- [ ] Support for different content formats
+- [ ] Add content indexing status checking
+- [ ] Implement content caching strategies
+
+### 4.4 Create streaming API support  
+- [ ] Research and implement Zotero streaming API endpoints
+- [ ] Add real-time update notifications
+- [ ] Create event-based update handling
+- [ ] Implement connection management for streaming
+- [ ] Add streaming API error recovery
+
+### 4.5 Add pagination handling
+- [ ] Implement automatic pagination with `Link` header parsing
+- [ ] Create iterator pattern for paginated results
+- [ ] Add configurable page size limits
+- [ ] Support for cursor-based pagination where available
+- [ ] Implement efficient pagination caching
+
+## Phase 5: Developer Experience & Polish
+
+### 5.1 Create comprehensive test suite
+- [ ] Write unit tests for all major classes and methods
+- [ ] Add integration tests using VCR for API mocking
+- [ ] Create test fixtures for different Zotero data types
+- [ ] Implement contract tests for API compatibility
+- [ ] Add performance benchmarks and regression tests
+- [ ] Achieve >90% test coverage
+
+### 5.2 Add configuration management
+- [ ] Create global configuration system (`Zotero.configure`)
+- [ ] Add environment variable support for common settings
+- [ ] Implement per-client configuration overrides
+- [ ] Add validation for configuration options
+- [ ] Create configuration presets for common use cases
+
+### 5.3 Write detailed documentation
+- [ ] Generate comprehensive API reference with YARD
+- [ ] Create usage guides and tutorials
+- [ ] Add code examples for common patterns
+- [ ] Document authentication setup and OAuth flow
+- [ ] Create troubleshooting guide and FAQ
+
+### 5.4 Performance optimization
+- [ ] Implement HTTP connection pooling
+- [ ] Add request batching where possible
+- [ ] Optimize JSON parsing and object creation
+- [ ] Implement intelligent caching strategies
+- [ ] Add memory usage profiling and optimization
+
+### 5.5 Add Ruby 3+ compatibility
+- [ ] Ensure compatibility with Ruby 3.1+ features
+- [ ] Add support for keyword arguments
+- [ ] Update code to use modern Ruby idioms
+- [ ] Test with Ruby 3.3+ and handle deprecations
+- [ ] Add Ractor safety where applicable
+
+## Quality Gates
+
+Each major phase should meet these criteria before proceeding:
+
+- [ ] All tests passing
+- [ ] RuboCop violations resolved
+- [ ] Documentation updated
+- [ ] CHANGELOG updated
+- [ ] Version bumped appropriately
+- [ ] Manual testing completed
+
+## Future Considerations
+
+- **GraphQL Support**: If Zotero adds GraphQL endpoints
+- **WebSocket Integration**: For real-time updates
+- **Bulk Operations**: Optimized bulk import/export
+- **Plugin System**: Allow third-party extensions
+- **CLI Tool**: Command-line interface for common operations
+- **Rails Integration**: ActiveRecord-style models and associations
+
+---
+
+**Last Updated**: 2025-08-31  
+**Gem Name**: zotero-rb  
+**Target Ruby Version**: 3.1+  
+**Zotero API Version**: v3

data/lib/zotero/client.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "httparty"
+require_relative "item_types"
+require_relative "fields"
+require_relative "file_upload"
+require_relative "http_errors"
+require_relative "syncing"
+
+module Zotero
+  # The main HTTP client for interacting with the Zotero Web API v3.
+  # Provides authentication, request handling, and access to library operations.
+  #
+  # @example Create a client with API key
+  #   client = Zotero::Client.new(api_key: 'your-api-key-here')
+  #   library = client.user_library(12345)
+  #
+  class Client
+    include HTTParty
+    include ItemTypes
+    include Fields
+    include FileUpload
+    include HTTPErrors
+    include Syncing
+
+    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
+    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
+    # @return [Library] A Library instance for the specified user
+    def user_library(user_id)
+      Library.new(client: self, type: :user, id: user_id)
+    end
+
+    # Get a Library instance for a specific group.
+    #
+    # @param group_id [Integer, String] The Zotero group ID
+    # @return [Library] A Library instance for the specified group
+    def group_library(group_id)
+      Library.new(client: self, type: :group, id: group_id)
+    end
+
+    private
+
+    attr_reader :api_key
+
+    def auth_headers
+      { "Zotero-API-Key" => api_key }
+    end
+
+    def default_headers
+      { "Zotero-API-Version" => "3" }
+    end
+
+    def build_write_headers(version: nil, write_token: nil)
+      headers = auth_headers.merge(default_headers)
+      headers["Content-Type"] = "application/json"
+      headers["If-Unmodified-Since-Version"] = version.to_s if version
+      headers["Zotero-Write-Token"] = write_token if write_token
+      headers
+    end
+
+    def handle_response(response, format = nil)
+      return parse_response_body(response, format) if response.code.between?(200, 299)
+
+      raise_error_for_status(response)
+    end
+
+    def handle_write_response(response)
+      case response.code
+      when 200
+        response.parsed_response
+      when 204
+        true
+      else
+        raise_error_for_status(response)
+      end
+    end
+
+    def parse_response_body(response, format)
+      case format&.to_s
+      when "json", nil
+        response.parsed_response
+      else
+        response.body
+      end
+    end
+  end
+end

data/lib/zotero/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Zotero
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; 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
+end

data/lib/zotero/fields.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zotero
+  # Field discovery methods
+  module Fields
+    def item_fields(locale: nil)
+      get("/itemFields", params: build_locale_params(locale))
+    end
+
+    def creator_fields(locale: nil)
+      get("/creatorFields", params: build_locale_params(locale))
+    end
+
+    private
+
+    def build_locale_params(locale)
+      locale ? { locale: locale } : {}
+    end
+  end
+end

data/lib/zotero/file_upload.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Zotero
+  # File upload methods for handling attachment uploads
+  module FileUpload
+    def post_form(path, form_data:, if_match: nil, if_none_match: nil, params: {})
+      headers = auth_headers.merge(default_headers)
+      headers["Content-Type"] = "application/x-www-form-urlencoded"
+      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)
+      handle_response(response)
+    end
+
+    def external_post(url, multipart_data:)
+      response = self.class.post(url, body: multipart_data, multipart: true, format: :plain)
+
+      case response.code
+      when 200..299
+        response.body
+      else
+        raise Error, "External upload failed: HTTP #{response.code} - #{response.message}"
+      end
+    end
+
+    def request_upload_authorization(path, filename:, md5: nil, mtime: nil, existing_file: false)
+      form_data = { upload: filename, md5: md5, mtime: mtime }.compact
+
+      if existing_file
+        post_form(path, form_data: form_data, if_match: md5.to_s)
+      else
+        post_form(path, form_data: form_data, if_none_match: "*")
+      end
+    end
+
+    def register_upload(path, upload_key:)
+      post_form(path, form_data: { upload: upload_key })
+    end
+  end
+end

data/lib/zotero/fulltext.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Zotero
+  module Fulltext
+    def fulltext_since(since:)
+      @client.get("#{@base_path}/fulltext", params: { since: since })
+    end
+
+    def item_fulltext(item_key)
+      @client.get("#{@base_path}/items/#{item_key}/fulltext")
+    end
+
+    def set_item_fulltext(item_key, content_data, version: nil)
+      @client.put("#{@base_path}/items/#{item_key}/fulltext", data: content_data, version: version)
+    end
+  end
+end

data/lib/zotero/http_errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Zotero
+  # HTTP error handling methods
+  module HTTPErrors
+    def raise_error_for_status(response)
+      case response.code
+      when 400..428 then raise_client_error(response)
+      when 429 then raise_rate_limit_error(response)
+      else raise_server_or_unknown_error(response)
+      end
+    end
+
+    def raise_client_error(response)
+      case response.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 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}"
+      end
+    end
+
+    def raise_rate_limit_error(response)
+      backoff = response.headers["backoff"]&.to_i
+      retry_after = response.headers["retry-after"]&.to_i
+      message = "Rate limited."
+      message += " Backoff: #{backoff}s" if backoff
+      message += " Retry after: #{retry_after}s" if retry_after
+      raise RateLimitError, message
+    end
+
+    def raise_server_or_unknown_error(response)
+      case response.code
+      when 500..599
+        raise ServerError, "Server error: HTTP #{response.code} - #{response.message}"
+      else
+        raise Error, "Unexpected response: HTTP #{response.code} - #{response.message}"
+      end
+    end
+  end
+end

data/lib/zotero/item_types.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Zotero
+  # Item type discovery and template methods
+  module ItemTypes
+    def item_types(locale: nil)
+      get("/itemTypes", params: build_locale_params(locale))
+    end
+
+    def item_type_fields(item_type, locale: nil)
+      params = { itemType: item_type }
+      params.merge!(build_locale_params(locale))
+      get("/itemTypeFields", params: params)
+    end
+
+    def item_type_creator_types(item_type)
+      get("/itemTypeCreatorTypes", params: { itemType: item_type })
+    end
+
+    def new_item_template(item_type)
+      get("/items/new", params: { itemType: item_type })
+    end
+
+    private
+
+    def build_locale_params(locale)
+      locale ? { locale: locale } : {}
+    end
+  end
+end

data/lib/zotero/library.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "library_file_operations"
+require_relative "fulltext"
+require_relative "syncing"
+
+module Zotero
+  # Represents a Zotero library (user or group) and provides methods for
+  # managing items, collections, tags, searches, and file operations.
+  #
+  # @example Working with a user library
+  #   client = Zotero.new(api_key: 'your-key')
+  #   library = client.user_library(12345)
+  #   items = library.items
+  #   collections = library.collections
+  #
+  class Library
+    # TODO: rename this module, LibraryFileOperations sounds weird
+    include LibraryFileOperations
+    include Fulltext
+    include Syncing
+
+    VALID_TYPES = %w[user group].freeze
+
+    # Initialize a new Library instance.
+    #
+    # @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)
+    def initialize(client:, type:, id:)
+      @client = client
+      @type = validate_type(type)
+      @id = id
+      @base_path = "/#{@type}s/#{@id}"
+    end
+
+    # Get collections in this library.
+    #
+    # @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)
+    end
+
+    # Get items in this library.
+    #
+    # @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)
+    end
+
+    def searches(**params)
+      @client.get("#{@base_path}/searches", params: params)
+    end
+
+    def tags(**params)
+      @client.get("#{@base_path}/tags", params: params)
+    end
+
+    # Create a new item in this library.
+    #
+    # @param item_data [Hash] The item 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_item(item_data, version: nil, write_token: nil)
+      create_single("items", item_data, version: version, write_token: write_token)
+    end
+
+    def create_items(items_array, version: nil, write_token: nil)
+      create_multiple("items", items_array, version: version, write_token: write_token)
+    end
+
+    def update_item(item_key, item_data, version: nil)
+      @client.patch("#{@base_path}/items/#{item_key}", data: item_data, version: version)
+    end
+
+    def delete_item(item_key, version: nil)
+      @client.delete("#{@base_path}/items/#{item_key}", version: version)
+    end
+
+    def delete_items(item_keys, version: nil)
+      @client.delete("#{@base_path}/items", version: version, params: { itemKey: item_keys.join(",") })
+    end
+
+    def create_collection(collection_data, version: nil, write_token: nil)
+      create_single("collections", collection_data, version: version, write_token: write_token)
+    end
+
+    def create_collections(collections_array, version: nil, write_token: nil)
+      create_multiple("collections", collections_array, version: version, write_token: write_token)
+    end
+
+    def update_collection(collection_key, collection_data, version: nil)
+      @client.patch("#{@base_path}/collections/#{collection_key}", data: collection_data, version: version)
+    end
+
+    def delete_collection(collection_key, version: nil)
+      @client.delete("#{@base_path}/collections/#{collection_key}", version: version)
+    end
+
+    def delete_collections(collection_keys, version: nil)
+      @client.delete("#{@base_path}/collections", version: version,
+                                                  params: { collectionKey: collection_keys.join(",") })
+    end
+
+    private
+
+    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)
+    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)
+    end
+
+    def validate_type(type)
+      type_str = type.to_s
+      unless VALID_TYPES.include?(type_str)
+        raise ArgumentError, "Invalid library type: #{type_str}. Must be one of: #{VALID_TYPES.join(', ')}"
+      end
+
+      type_str
+    end
+  end
+end

data/lib/zotero/library_file_operations.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Zotero
+  # File upload operations for library items
+  module LibraryFileOperations
+    def create_attachment(attachment_data, version: nil, write_token: nil)
+      create_single("items", attachment_data, version: version, write_token: write_token)
+    end
+
+    def get_file_info(item_key)
+      @client.get("#{@base_path}/items/#{item_key}/file")
+    end
+
+    def upload_file(item_key, file_path)
+      perform_file_upload(item_key, file_path, existing_file: false)
+    end
+
+    def update_file(item_key, file_path)
+      perform_file_upload(item_key, file_path, existing_file: true)
+    end
+
+    private
+
+    def perform_file_upload(item_key, file_path, existing_file:)
+      file_metadata = extract_file_metadata(file_path)
+      upload_path = file_upload_path(item_key)
+
+      # Step 1: Request upload authorization
+      auth_response = @client.request_upload_authorization(
+        upload_path,
+        **file_metadata,
+        existing_file: existing_file
+      )
+
+      perform_external_upload(auth_response, file_path, upload_path)
+    end
+
+    def extract_file_metadata(file_path)
+      require "digest"
+
+      {
+        filename: File.basename(file_path),
+        md5: Digest::MD5.file(file_path).hexdigest,
+        mtime: File.mtime(file_path).to_i * 1000 # Convert to milliseconds
+      }
+    end
+
+    def file_upload_path(item_key)
+      "#{@base_path}/items/#{item_key}/file"
+    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
+
+      if auth_response["uploadKey"]
+        @client.register_upload(upload_path, upload_key: auth_response["uploadKey"])
+      else
+        true
+      end
+    end
+
+    def build_upload_params(auth_response, file_path)
+      file_data = File.open(file_path, "rb")
+
+      if auth_response["params"]
+        auth_response["params"].merge("file" => file_data)
+      else
+        {
+          "prefix" => auth_response["prefix"],
+          "file" => file_data,
+          "suffix" => auth_response["suffix"]
+        }
+      end
+    end
+  end
+end

data/lib/zotero/syncing.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Zotero
+  module Syncing
+    def verify_api_key
+      @client ? @client.get("/keys/current") : get("/keys/current")
+    end
+
+    def user_groups(user_id, format: "versions")
+      client = @client || self
+      client.get("/users/#{user_id}/groups", params: { format: format })
+    end
+
+    def deleted_items(since: nil)
+      params = since ? { since: since } : {}
+      @client.get("#{@base_path}/deleted", params: params)
+    end
+  end
+end

data/lib/zotero/version.rb

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

data/lib/zotero.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "zotero/version"
+require_relative "zotero/client"
+require_relative "zotero/library"
+require_relative "zotero/error"
+
+# Ruby client library for the Zotero Web API v3.
+#
+# Provides a comprehensive interface for interacting with Zotero libraries,
+# including full CRUD operations for items, collections, tags, searches,
+# file uploads, and synchronization.
+#
+# @example Basic usage
+#   client = Zotero.new(api_key: 'your-api-key')
+#   library = client.user_library(12345)
+#   items = library.items
+#
+# @see https://www.zotero.org/support/dev/web_api/v3/start Zotero Web API v3 Documentation
+module Zotero
+  # Create a new Zotero API client.
+  #
+  # @param api_key [String] Your Zotero API key
+  # @return [Client] A new Zotero client instance
+  def self.new(api_key:)
+    Client.new(api_key: api_key)
+  end
+end

data/sig/zotero/rb.rbs

@@ -0,0 +1,6 @@
+module Zotero
+  module Rb
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: zotero-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Andrew Waller
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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
+- !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'
+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
+  comprehensive error handling.
+email:
+- 48367637+andrewhwaller@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- TASKS.md
+- lib/zotero.rb
+- lib/zotero/client.rb
+- lib/zotero/error.rb
+- lib/zotero/fields.rb
+- lib/zotero/file_upload.rb
+- lib/zotero/fulltext.rb
+- lib/zotero/http_errors.rb
+- lib/zotero/item_types.rb
+- lib/zotero/library.rb
+- lib/zotero/library_file_operations.rb
+- lib/zotero/syncing.rb
+- lib/zotero/version.rb
+- sig/zotero/rb.rbs
+homepage: https://github.com/andrewhwaller/zotero-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/andrewhwaller/zotero-rb/issues
+  documentation_uri: https://rubydoc.info/gems/zotero-rb
+  wiki_uri: https://github.com/andrewhwaller/zotero-rb/wiki
+  homepage_uri: https://github.com/andrewhwaller/zotero-rb
+  source_code_uri: https://github.com/andrewhwaller/zotero-rb
+  changelog_uri: https://github.com/andrewhwaller/zotero-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: A comprehensive Ruby client for the Zotero Web API v3
+test_files: []