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.

Raises:

  • (ArgumentError) —

    if type is invalid or id is not a positive integer



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

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

Instance Attribute Details

#base_path ⇒ Object (readonly, private)

Returns the value of attribute base_path.



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

def base_path
  @base_path
end

#client ⇒ Object (readonly, private)

Returns the value of attribute client.



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

def client
  @client
end

#id ⇒ Object (readonly, private)

Returns the value of attribute id.



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

def id
  @id
end

#type ⇒ Object (readonly, private)

Returns the value of attribute type.



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

def type
  @type
end

Instance Method Details

#api_client ⇒ Object (private) Originally defined in module Syncing

Returns the object that handles API requests. Override in including classes if needed.

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

#collections(**params) ⇒ Array, Hash

Get collections in this library.



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

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.

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

Create a new collection in this library.



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

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.



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

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.



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

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.



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

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) 



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

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) 



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

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.



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

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.



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

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.



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

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.



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

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. Only available when included in Library.

#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.

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

Get file information for an attachment item.

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

Get the fulltext content for a specific item.

#items(**params) ⇒ Array, Hash

Get items in this library.



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

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

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

#searches(**params) ⇒ Array, Hash

Get saved searches in this library.



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

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.

#tags(**params) ⇒ Array, Hash

Get tags in this library.



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

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.



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

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.

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

Update an existing item in this library.



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

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.

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

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

Get groups for a specific user.

#validate_id(id) ⇒ Object (private)

Raises:

  • (ArgumentError) 


195
196
197
198
199
200
 
# File 'lib/zotero/library.rb', line 195

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

#validate_type(type) ⇒ Object (private) 



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

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.