paperless-api 0.4.0

Async Paperless ngx API client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! A small async client for interacting with the Paperless-ngx API.
//!
//! This crate provides [`PaperlessClient`] for talking to a Paperless instance and
//! convenience types for working with documents, tags, custom fields, correspondents,
//! document types, and tasks.
//!
//! # Getting started
//!
//! Create a client with your Paperless base URL and API token:
//!
//! ```no_run
//! use paperless_api::PaperlessClient;
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! let client = PaperlessClient::new(
//!     "https://paperless.example.com",
//!     "your-api-token",
//!     None,
//! )?;
//! # let _ = client;
//! # Ok(())
//! # }
//! ```
//!
//! # Refreshing cached metadata
//!
//! The client keeps some metadata cached locally, such as tags, custom fields,
//! correspondents, and document types.
//!
//! You can refresh individual caches:
//!
//! ```no_run
//! use paperless_api::PaperlessClient;
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! let mut client = PaperlessClient::new(
//!     "https://paperless.example.com",
//!     "your-api-token",
//!     None,
//! )?;
//!
//! client.refresh_tags().await?;
//! client.refresh_custom_fields().await?;
//! # Ok(())
//! # }
//! ```
//!
//! Or refresh multiple datasets at once:
//!
//! ```no_run
//! use paperless_api::{PaperlessClient, RefreshData};
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! let mut client = PaperlessClient::new(
//!     "https://paperless.example.com",
//!     "your-api-token",
//!     None,
//! )?;
//!
//! client.refresh([RefreshData::Tags, RefreshData::CustomFields]).await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Working with tags
//!
//! After refreshing tags, you can look them up from the local cache:
//!
//! ```no_run
//! use paperless_api::PaperlessClient;
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! let mut client = PaperlessClient::new(
//!     "https://paperless.example.com",
//!     "your-api-token",
//!     None,
//! )?;
//!
//! client.refresh_tags().await?;
//!
//! if let Some(tag) = client.find_tag_by_name("invoice") {
//!     let docs = client.get_documents_by_tags(&[tag.id], true).await?;
//!     println!("found {} documents", docs.len());
//! }
//! # Ok(())
//! # }
//! ```

pub mod client;
pub mod correspondent;
pub mod custom_field;
pub mod document;
pub mod document_type;
pub mod id;
pub mod note;
pub mod share_link;
pub mod tag;
pub mod task;
pub mod user;
pub mod workflow;

pub use client::{PaperlessClient, RefreshData};
pub use custom_field::{CustomField, DocumentCustomField};
pub use document::Document;
pub use tag::Tag;
pub use task::Task;
pub use user::User;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("response error: status code {status_code}, body: {body}")]
    Response { status_code: u16, body: String },

    #[error(transparent)]
    Request(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),

    #[error("other error: {0}")]
    Other(String),

    #[error("invalid json: {0}")]
    InvalidJson(String),

    #[error("not found")]
    NotFound,

    #[error("not changeable")]
    NotChangeable,

    #[error("already deleted")]
    AlreadyDeleted,
}

type Result<T> = std::result::Result<T, Error>;