Module: Zotero::FileAttachments

Included in:
Library
Defined in:
lib/zotero/file_attachments.rb

Overview

File attachment operations for library items

Instance Method Summary collapse

Instance Method Details

#build_upload_params(auth_response, file_path) ⇒ Object (private) 



85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/zotero/file_attachments.rb', line 85

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

#create_attachment(attachment_data, version: nil, write_token: nil) ⇒ Hash

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



14
15
16
 
# File 'lib/zotero/file_attachments.rb', line 14

def create_attachment(attachment_data, version: nil, write_token: nil)
  create_single("items", attachment_data, version: version, write_token: write_token)
end

#extract_file_metadata(file_path) ⇒ Object (private) 



60
61
62
63
64
65
66
 
# File 'lib/zotero/file_attachments.rb', line 60

def extract_file_metadata(file_path)
  {
    filename: File.basename(file_path),
    md5: Digest::MD5.file(file_path).hexdigest,
    mtime: File.mtime(file_path).to_i * 1000 # Convert to milliseconds
  }
end

#file_upload_path(item_key) ⇒ Object (private) 



68
69
70
 
# File 'lib/zotero/file_attachments.rb', line 68

def file_upload_path(item_key)
  "#{@base_path}/items/#{item_key}/file"
end

#get_file_info(item_key) ⇒ Hash

Get file information for an attachment item.

Parameters:

  • item_key (String) —

    The attachment item key

Returns:

  • (Hash) —

    File information including filename, md5, mtime



22
23
24
 
# File 'lib/zotero/file_attachments.rb', line 22

def get_file_info(item_key)
  @client.make_get_request("#{@base_path}/items/#{item_key}/file")
end

#perform_external_upload(auth_response, file_path, upload_path) ⇒ Object (private) 



72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/zotero/file_attachments.rb', line 72

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

#perform_file_upload(item_key, file_path, existing_file:) ⇒ Object (private) 



46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/zotero/file_attachments.rb', line 46

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

#update_file(item_key, file_path) ⇒ Boolean

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



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

def update_file(item_key, file_path)
  perform_file_upload(item_key, file_path, existing_file: true)
end

#upload_file(item_key, file_path) ⇒ Boolean

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



31
32
33
 
# File 'lib/zotero/file_attachments.rb', line 31

def upload_file(item_key, file_path)
  perform_file_upload(item_key, file_path, existing_file: false)
end