paperless-api 0.2.1

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

//! 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 tag;
pub mod task;
pub mod user;

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,
}

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