Class: Zotero::Library

Inherits:
Object
  • Object
show all
Includes:
FileAttachments, Fulltext, Syncing
Defined in:
lib/zotero/library.rb

Overview

Represents a Zotero library (user or group) and provides methods for managing items, collections, tags, searches, and file operations.

Examples:

Working with a user library

client = Zotero.new(api_key: 'your-key')
library = client.user_library(12345)
items = library.items
collections = library.collections

Constant Summary collapse

VALID_TYPES = 
%w[user group].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:, type:, id:) ⇒ Library

Initialize a new Library instance.

Parameters:

  • client (Client) —

    The Zotero client instance

  • type (String, Symbol) —

    The library type (:user or :group)

  • id (Integer, String) —

    The library ID (user ID or group ID)



29
30
31
32
33
34
 
# File 'lib/zotero/library.rb', line 29

def initialize(client:, type:, id:)
  @client = client
  @type = validate_type(type)
  @id = id
  @base_path = "/#{@type}s/#{@id}"
end

Instance Attribute Details

#base_path ⇒ Object (readonly, private)

Returns the value of attribute base_path.



171
172
173
 
# File 'lib/zotero/library.rb', line 171

def base_path
  @base_path
end

#client ⇒ Object (readonly, private)

Returns the value of attribute client.



171
172
173
 
# File 'lib/zotero/library.rb', line 171

def client
  @client
end

#id ⇒ Object (readonly, private)

Returns the value of attribute id.



171
172
173
 
# File 'lib/zotero/library.rb', line 171

def id
  @id
end

#type ⇒ Object (readonly, private)

Returns the value of attribute type.



171
172
173
 
# File 'lib/zotero/library.rb', line 171

def type
  @type
end

Instance Method Details

#build_upload_params(auth_response, file_path) ⇒ Object (private) Originally defined in module FileAttachments

#collections(**params) ⇒ Array, Hash

Get collections in this library.

Parameters:

  • params (Hash) —

    Query parameters for the request

Returns:

  • (Array, Hash) —

    Collections data from the API



40
41
42
 
# File 'lib/zotero/library.rb', line 40

def collections(**params)
  @client.make_get_request("#{@base_path}/collections", params: params)
end

#create_attachment(attachment_data, version: nil, write_token: nil) ⇒ Hash Originally defined in module FileAttachments

Create a new attachment item in the library.

Parameters:

  • attachment_data (Hash) —

    The attachment data including itemType, contentType, etc.

  • version (Integer) (defaults to: nil) —

    Optional version for conditional requests

  • write_token (String) (defaults to: nil) —

    Optional write token for batch operations

Returns:

  • (Hash) —

    The API response with created attachment

#create_collection(collection_data, version: nil, write_token: nil) ⇒ Hash

Create a new collection in this library.

Parameters:

  • collection_data (Hash) —

    The collection data

  • version (Integer) (defaults to: nil) —

    Optional version for conditional requests

  • write_token (String) (defaults to: nil) —

    Optional write token for batch operations

Returns:

  • (Hash) —

    The API response



124
125
126
 
# File 'lib/zotero/library.rb', line 124

def create_collection(collection_data, version: nil, write_token: nil)
  create_single("collections", collection_data, version: version, write_token: write_token)
end

#create_collections(collections_array, version: nil, write_token: nil) ⇒ Hash

Create multiple collections in this library.

Parameters:

  • collections_array (Array<Hash>) —

    Array of collection data objects

  • version (Integer) (defaults to: nil) —

    Optional version for conditional requests

  • write_token (String) (defaults to: nil) —

    Optional write token for batch operations

Returns:

  • (Hash) —

    The API response with created collections



134
135
136
 
# File 'lib/zotero/library.rb', line 134

def create_collections(collections_array, version: nil, write_token: nil)
  create_multiple("collections", collections_array, version: version, write_token: write_token)
end

#create_item(item_data, version: nil, write_token: nil) ⇒ Hash

Create a new item in this library.

Parameters:

  • item_data (Hash) —

    The item data

  • version (Integer) (defaults to: nil) —

    Optional version for conditional requests

  • write_token (String) (defaults to: nil) —

    Optional write token for batch operations

Returns:

  • (Hash) —

    The API response



74
75
76
 
# File 'lib/zotero/library.rb', line 74

def create_item(item_data, version: nil, write_token: nil)
  create_single("items", item_data, version: version, write_token: write_token)
end

#create_items(items_array, version: nil, write_token: nil) ⇒ Hash

Create multiple items in this library.

Parameters:

  • items_array (Array<Hash>) —

    Array of item data objects

  • version (Integer) (defaults to: nil) —

    Optional version for conditional requests

  • write_token (String) (defaults to: nil) —

    Optional write token for batch operations

Returns:

  • (Hash) —

    The API response with created items



84
85
86
 
# File 'lib/zotero/library.rb', line 84

def create_items(items_array, version: nil, write_token: nil)
  create_multiple("items", items_array, version: version, write_token: write_token)
end

#create_multiple(resource, data_array, version: nil, write_token: nil) ⇒ Object (private) 



179
180
181
182
183
 
# File 'lib/zotero/library.rb', line 179

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 })
end

#create_single(resource, data, version: nil, write_token: nil) ⇒ Object (private) 



173
174
175
176
177
 
# File 'lib/zotero/library.rb', line 173

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 })
end

#delete_collection(collection_key, version: nil) ⇒ Boolean

Delete a collection from this library.

Parameters:

  • collection_key (String) —

    The collection key to delete

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Boolean) —

    Success status



154
155
156
 
# File 'lib/zotero/library.rb', line 154

def delete_collection(collection_key, version: nil)
  @client.make_write_request(:delete, "#{@base_path}/collections/#{collection_key}", options: { version: version })
end

#delete_collections(collection_keys, version: nil) ⇒ Boolean

Delete multiple collections from this library.

Parameters:

  • collection_keys (Array<String>) —

    Array of collection keys to delete

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Boolean) —

    Success status



163
164
165
166
167
 
# File 'lib/zotero/library.rb', line 163

def delete_collections(collection_keys, version: nil)
  @client.make_write_request(:delete, "#{@base_path}/collections",
                             options: { version: version },
                             params: { collectionKey: collection_keys.join(",") })
end

#delete_item(item_key, version: nil) ⇒ Boolean

Delete an item from this library.

Parameters:

  • item_key (String) —

    The item key to delete

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Boolean) —

    Success status



104
105
106
 
# File 'lib/zotero/library.rb', line 104

def delete_item(item_key, version: nil)
  @client.make_write_request(:delete, "#{@base_path}/items/#{item_key}", options: { version: version })
end

#delete_items(item_keys, version: nil) ⇒ Boolean

Delete multiple items from this library.

Parameters:

  • item_keys (Array<String>) —

    Array of item keys to delete

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Boolean) —

    Success status



113
114
115
116
 
# File 'lib/zotero/library.rb', line 113

def delete_items(item_keys, version: nil)
  @client.make_write_request(:delete, "#{@base_path}/items", options: { version: version },
                                                             params: { itemKey: item_keys.join(",") })
end

#deleted_items(since: nil) ⇒ Hash Originally defined in module Syncing

Get items that have been deleted from this library.

Parameters:

  • since (Integer) (defaults to: nil) —

    Optional version to get deletions since

Returns:

  • (Hash) —

    Object with deleted collections and items arrays

#extract_file_metadata(file_path) ⇒ Object (private) Originally defined in module FileAttachments

#file_upload_path(item_key) ⇒ Object (private) Originally defined in module FileAttachments

#fulltext_since(since:) ⇒ Hash Originally defined in module Fulltext

Get fulltext content that has been modified since a given version.

Parameters:

  • since (Integer) —

    Version number to get changes since

Returns:

  • (Hash) —

    Object mapping item keys to version numbers

#get_file_info(item_key) ⇒ Hash Originally defined in module FileAttachments

Get file information for an attachment item.

Parameters:

  • item_key (String) —

    The attachment item key

Returns:

  • (Hash) —

    File information including filename, md5, mtime

#item_fulltext(item_key) ⇒ Hash Originally defined in module Fulltext

Get the fulltext content for a specific item.

Parameters:

  • item_key (String) —

    The item key to get fulltext for

Returns:

  • (Hash) —

    Fulltext content data including content, indexedChars, and totalChars

#items(**params) ⇒ Array, Hash

Get items in this library.

Parameters:

  • params (Hash) —

    Query parameters for the request

Returns:

  • (Array, Hash) —

    Items data from the API



48
49
50
 
# File 'lib/zotero/library.rb', line 48

def items(**params)
  @client.make_get_request("#{@base_path}/items", params: params)
end

#perform_external_upload(auth_response, file_path, upload_path) ⇒ Object (private) Originally defined in module FileAttachments

#perform_file_upload(item_key, file_path, existing_file:) ⇒ Object (private) Originally defined in module FileAttachments

#searches(**params) ⇒ Array, Hash

Get saved searches in this library.

Parameters:

  • params (Hash) —

    Query parameters for the request

Returns:

  • (Array, Hash) —

    Saved searches data from the API



56
57
58
 
# File 'lib/zotero/library.rb', line 56

def searches(**params)
  @client.make_get_request("#{@base_path}/searches", params: params)
end

#set_item_fulltext(item_key, content_data, version: nil) ⇒ Boolean Originally defined in module Fulltext

Set the fulltext content for a specific item.

Parameters:

  • item_key (String) —

    The item key to set fulltext for

  • content_data (Hash) —

    Fulltext content data with content, indexedChars, totalChars

  • version (Integer) (defaults to: nil) —

    Optional version for optimistic concurrency control

Returns:

  • (Boolean) —

    Success status

#tags(**params) ⇒ Array, Hash

Get tags in this library.

Parameters:

  • params (Hash) —

    Query parameters for the request

Returns:

  • (Array, Hash) —

    Tags data from the API



64
65
66
 
# File 'lib/zotero/library.rb', line 64

def tags(**params)
  @client.make_get_request("#{@base_path}/tags", params: params)
end

#update_collection(collection_key, collection_data, version: nil) ⇒ Hash

Update an existing collection in this library.

Parameters:

  • collection_key (String) —

    The collection key to update

  • collection_data (Hash) —

    The updated collection data

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Hash) —

    The API response



144
145
146
147
 
# File 'lib/zotero/library.rb', line 144

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 })
end

#update_file(item_key, file_path) ⇒ Boolean Originally defined in module FileAttachments

Update the file content of an existing attachment.

Parameters:

  • item_key (String) —

    The attachment item key

  • file_path (String) —

    Local path to the new file

Returns:

  • (Boolean) —

    Success status

#update_item(item_key, item_data, version: nil) ⇒ Hash

Update an existing item in this library.

Parameters:

  • item_key (String) —

    The item key to update

  • item_data (Hash) —

    The updated item data

  • version (Integer) (defaults to: nil) —

    Version for optimistic concurrency control

Returns:

  • (Hash) —

    The API response



94
95
96
97
 
# File 'lib/zotero/library.rb', line 94

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 })
end

#upload_file(item_key, file_path) ⇒ Boolean Originally defined in module FileAttachments

Upload a file to an attachment item.

Parameters:

  • item_key (String) —

    The attachment item key

  • file_path (String) —

    Local path to the file to upload

Returns:

  • (Boolean) —

    Success status

#user_groups(user_id, format: "versions") ⇒ Hash, Array Originally defined in module Syncing

Get groups for a specific user.

Parameters:

  • user_id (Integer, String) —

    The user ID to get groups for

  • format (String) (defaults to: "versions") —

    Response format ('versions' or 'json')

Returns:

  • (Hash, Array) —

    Groups data in the requested format

#validate_type(type) ⇒ Object (private) 



185
186
187
188
189
190
191
192
 
# File 'lib/zotero/library.rb', line 185

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

#verify_api_key ⇒ Hash Originally defined in module Syncing

Verify that the current API key is valid.

Returns:

  • (Hash) —

    API key information including userID and username