papers_zotero/lib.rs
1//! Async Rust client for the [Zotero Web API v3](https://www.zotero.org/support/dev/web_api/v3/start).
2//!
3//! Zotero is a personal research library manager. This crate provides a
4//! type-safe async client for reading items, collections, tags, searches,
5//! and groups from a Zotero user or group library.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! # async fn example() -> papers_zotero::Result<()> {
11//! use papers_zotero::{ZoteroClient, ItemListParams};
12//!
13//! let client = ZoteroClient::new("16916553", "your-api-key");
14//!
15//! // Search for items about rendering
16//! let params = ItemListParams::builder()
17//! .q("rendering")
18//! .limit(5)
19//! .build();
20//! let response = client.list_items(¶ms).await?;
21//! println!("Found {:?} items", response.total_results);
22//! for item in &response.items {
23//! println!(" - {}", item.data.title.as_deref().unwrap_or("untitled"));
24//! }
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! # Authentication
30//!
31//! A Zotero API key is required. Create one at
32//! <https://www.zotero.org/settings/keys>. Pass it explicitly or set the
33//! `ZOTERO_API_KEY` and `ZOTERO_USER_ID` environment variables:
34//!
35//! ```no_run
36//! use papers_zotero::ZoteroClient;
37//!
38//! // Explicit credentials
39//! let client = ZoteroClient::new("16916553", "your-key");
40//!
41//! // Or from environment
42//! let client = ZoteroClient::from_env().unwrap();
43//! ```
44//!
45//! # Endpoints
46//!
47//! The client provides 40+ methods covering all Zotero read and write endpoints:
48//!
49//! **Read:**
50//! - **9 item endpoints** — list/get items, top items, trash, children,
51//! collection items, publication items, file download, file view, file URL
52//! - **4 collection endpoints** — list/get collections, top, subcollections
53//! - **10 tag endpoints** — list tags across various scopes (items, collections,
54//! trash, publications)
55//! - **2 search endpoints** — list/get saved searches
56//! - **2 full-text endpoints** — list indexed versions, get item full-text
57//! - **1 deleted endpoint** — get deleted object keys since a version
58//! - **2 settings endpoints** — get all settings, get single setting
59//! - **1 group endpoint** — list user groups
60//! - **2 key endpoints** — get API key info by value or by current request
61//!
62//! **Write:**
63//! - **5 item write endpoints** — create, update (PUT), patch (PATCH),
64//! delete single, delete multiple
65//! - **4 collection write endpoints** — create, update, delete single,
66//! delete multiple
67//! - **2 search write endpoints** — create, delete multiple
68//! - **1 tag write endpoint** — delete multiple tags
69
70pub mod cache;
71pub mod client;
72pub mod error;
73pub mod params;
74pub mod response;
75pub mod types;
76
77pub use cache::DiskCache;
78pub use client::ZoteroClient;
79pub use error::{Result, ZoteroError};
80pub use params::{CollectionListParams, DeletedParams, FulltextParams, ItemListParams, TagListParams};
81pub use response::{PagedResponse, VersionedResponse};
82pub use types::*;