Skip to main content

crossref_client/
lib.rs

1//! An async client for the [Crossref REST API](https://api.crossref.org/swagger-ui/index.html).
2//!
3//! `crossref-client` is a hard fork of [`crossref-rs`](https://github.com/MattsSe/crossref-rs)
4//! and has diverged substantially from it; changes are not upstreamed.
5//!
6//! The [`Crossref`] client provides methods matching the Crossref API routes:
7
8//! * `works` - `/works` route
9//! * `members` - `/members` route
10//! * `prefixes` - `/prefixes` route
11//! * `funders` - `/funders` route
12//! * `journals` - `/journals` route
13//! * `licenses` - `/licenses` route
14//! * `types` - `/types` route
15//! * `agency` - `/works/{doi}/agency` get DOI minting agency
16//!
17//! ## Usage
18
19//! ### Create a `Crossref` client:
20
21//! ```no_run
22//! # use crossref_client::Crossref;
23//! # async fn run() -> Result<(), crossref_client::Error> {
24//! let client = Crossref::builder().build()?;
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! If you have an [Authorization token for Crossref's Plus service](https://github.com/CrossRef/rest-api-doc#authorization-token-for-plus-service):
30//!
31//! ```no_run
32//! # use crossref_client::Crossref;
33//! # async fn run() -> Result<(), crossref_client::Error> {
34//! let client = Crossref::builder()
35//! .token("token")
36//! .build()?;
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! Encouraged to use the **The Polite Pool**:
42//!
43//! [Good manners = more reliable service](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
44//!
45//! To get into Crossref's polite pool include a email address
46//!
47//! ```no_run
48//! # use crossref_client::Crossref;
49//! # async fn run() -> Result<(), crossref_client::Error> {
50//! let client = Crossref::builder()
51//!     .polite("polite@example.com")
52//!     .token("your token")
53//!     .build()?;
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! ### Constructing Queries
59//! Not all components support queries and there are custom available parameters for each route that supports querying.
60//! For each resource components that supports querying there exist a Query struct: `WorksQuery`, `MembersQuery`, `FundersQuery`. The `WorksQuery` also differs from the others by supporting [deep paging with cursors](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors) and [field queries](https://github.com/CrossRef/rest-api-doc#works-field-queries).
61//!
62//! Otherwise creating queries works the same for all resource components:
63//!
64//! ```no_run
65//! # use crossref_client::*;
66//! # async fn run() -> crossref_client::Result<()> {
67//! let query = WorksQuery::new("Machine Learning")
68//! // field queries supported for `Works`
69//! .field_query(FieldQuery::author("Some Author"))
70//! // filters are specific for each resource component
71//! .filter(WorksFilter::HasOrcid)
72//! .order(Order::Asc)
73//! .sort(Sort::Score);
74//! # Ok(())
75//! # }
76//! ```
77//!
78//!
79//! ### Get Records
80//!
81//! See [this table](https://github.com/CrossRef/rest-api-doc#resource-components) for a detailed overview of the major components.
82//!
83//! There are 3 available targets:
84//!
85//! * **standalone resource components**: `/works`, `/members`, etc. that return a list list of the corresponding items and can be specified with queries
86//! * **Resource component with identifiers**: `/works/{doi}?<query>`,`/members/{member_id}?<query>`, etc. that returns a single item if found.
87//! * **combined with the `works` route**: The works component can be appended to other resources: `/members/{member_id}/works?<query>` etc. that returns a list of matching `Work` items.
88//!
89//! This resembles in the enums of the resource components, eg. for `Members`:
90//!
91//! ```no_run
92//! # use crossref_client::query::*;
93//! pub enum Members {
94//!     /// target a specific member at `/members/{id}`
95//!     Identifier(String),
96//!     /// target all members that match the query at `/members?query...`
97//!     Query(MembersQuery),
98//!     /// target a `Work` for a specific member at `/members/{id}/works?query..`
99//!     Works(WorksIdentQuery),
100//! }
101//! ```
102//!
103//! All options are supported by the client:
104//!
105//! **Single Item by DOI (ID)**
106//!
107//! Analogous methods exist for all resource components
108//!
109//! ```no_run
110//! # use crossref_client::*;
111//! # async fn run() -> crossref_client::Result<()> {
112//! # let client = Crossref::builder().build()?;
113//! let work = client.work("10.1037/0003-066X.59.1.29").await?;
114//!
115//! let agency = client.work_agency("10.1037/0003-066X.59.1.29").await?;
116//!
117//! let funder = client.funder("funder_id").await?;
118//!
119//! let member = client.member("member_id").await?;
120//! # Ok(())
121//! # }
122//! ```
123//!
124//! **Query**
125//!
126//! ```no_run
127//! # use crossref_client::*;
128//! # async fn run() -> crossref_client::Result<()> {
129//! # let client = Crossref::builder().build()?;
130//! let query = WorksQuery::new("Machine Learning");
131//!
132//! // one page of the matching results
133//! let works = client.works(query).await?;
134//! # Ok(())
135//! # }
136//! ```
137//!
138//! Alternatively insert a free form query term directly
139//!
140//! ```no_run
141//! # use crossref_client::*;
142//! # async fn run() -> crossref_client::Result<()> {
143//! # let client = Crossref::builder().build()?;
144//!
145//! // one page of the matching results
146//! let works = client.works("Machine Learning").await?;
147//! # Ok(())
148//! # }
149//! ```
150//!
151//! **Combining Routes with the `Works` route**
152//!
153//! For each resource component other than `Works` there exist methods to append a `WorksQuery` with the ID option `/members/{member_id}/works?<query>?`
154//!
155//! ```no_run
156//! # use crossref_client::*;
157//! # async fn run() -> crossref_client::Result<()> {
158//! # let client = Crossref::builder().build()?;
159//! let works = client.member_works( WorksQuery::new("machine learning")
160//! .sort(Sort::Score).into_ident("member_id")).await?;
161//! # Ok(())
162//! # }
163//! ```
164//!
165//! This would be the same as using the [`Crossref::works`] method by supplying the combined type
166//!
167//! ```no_run
168//! # use crossref_client::*;
169//! # async fn run() -> crossref_client::Result<()> {
170//! # let client = Crossref::builder().build()?;
171//! let works = client.works(WorksQuery::new("machine learning")
172//!     .sort(Sort::Score)
173//!     .into_combined_query::<Members>("member_id")).await?;
174//! # Ok(())
175//! # }
176//! ```
177//!
178//! ** Deep paging for `Works` **
179//! [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
180//! Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
181//! This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
182//! Usually a single page `WorkList` contains 20 items.
183//!
184//! # Example
185//!
186//! Iterate over all `Works` linked to search term `Machine Learning`
187//!
188//! ```no_run
189//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
190//! # async fn run() -> Result<(), crossref_client::Error> {
191//! let client = Crossref::builder().build()?;
192//!
193//! let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
194//! let mut all_works: Vec<Work> = Vec::new();
195//! while let Some(page) = pages.next().await {
196//!     let page = page?;
197//!     all_works.extend(page.items);
198//! }
199//!
200//! # Ok(())
201//! # }
202//! ```
203//!
204//! Which can be simplified to
205//!
206//! ```no_run
207//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
208//! # async fn run() -> Result<(), crossref_client::Error> {
209//! let client = Crossref::builder().build()?;
210//!
211//! let mut works = client.deep_page("Machine Learning").into_work_iter();
212//! let mut all_works: Vec<Work> = Vec::new();
213//! while let Some(work) = works.next().await {
214//!     let work = work?;
215//!     all_works.push(work);
216//! }
217//!
218//! # Ok(())
219//! # }
220//! ```
221//!
222//!
223//! # Example
224//!
225//! Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
226//! A single `WorkList` usually holds 20 `Work` items.
227//!
228//! ```no_run
229//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
230//! # async fn run() -> Result<(), crossref_client::Error> {
231//! let client = Crossref::builder().build()?;
232//!
233//! let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
234//! let mut all_funder_work_list: Vec<WorkList> = Vec::new();
235//! while let Some(page) = pages.next().await {
236//!     let page = page?;
237//!     all_funder_work_list.push(page);
238//! }
239//!
240//! # Ok(())
241//! # }
242//! ```
243//! # Example
244//!
245//! Iterate over all `Work` items of a specfic funder directly.
246//!
247//! ```no_run
248//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
249//! # async fn run() -> Result<(), crossref_client::Error> {
250//! let client = Crossref::builder().build()?;
251//!
252//! let mut works = client.deep_page(WorksQuery::default()
253//!         .into_combined_query::<Funders>("funder id"))
254//!         .into_work_iter();
255//! let mut all_works: Vec<Work> = Vec::new();
256//! while let Some(work) = works.next().await {
257//!     let work = work?;
258//!     all_works.push(work);
259//! }
260//!
261//! # Ok(())
262//! # }
263//! ```
264
265#![warn(missing_docs)]
266
267mod error;
268/// client side rate limiting
269pub mod limit;
270/// provides types to construct a specific query
271pub mod query;
272/// provides the response types of the crossref api
273pub mod response;
274
275/// content negotiation
276pub mod cn;
277
278#[doc(inline)]
279pub use self::error::{Error, Result};
280
281#[doc(inline)]
282pub use self::limit::RateLimit;
283
284#[doc(inline)]
285pub use self::cn::CnFormat;
286
287#[doc(inline)]
288pub use self::query::works::{
289    FieldQuery, WorkElement, WorkListQuery, WorkResultControl, Works, WorksFilter, WorksIdentQuery,
290    WorksQuery,
291};
292
293pub use self::query::facet::{Facet, FacetCount};
294pub use self::query::funders::{Funders, FundersFilter, FundersQuery};
295pub use self::query::members::{Members, MembersFilter, MembersQuery};
296#[doc(inline)]
297pub use self::query::{Component, CrossrefQuery, CrossrefRoute, Order, ResultControl, Sort};
298pub use self::query::{
299    Journals, JournalsQuery, Licenses, LicensesQuery, Prefixes, Type, Types, Visibility,
300    WorksComponent,
301};
302pub use self::response::{
303    CrossrefType, Failure, Failures, Funder, FunderList, Journal, JournalList, LicenseCount,
304    LicenseList, Member, MemberList, MessageType, StyleList, TypeList, Work, WorkAgency, WorkList,
305};
306
307/// The types that appear in the public fields of a [`Work`], re-exported so a
308/// caller of [`Crossref::works`] can name them without reaching into
309/// [`response::work`].
310#[doc(inline)]
311pub use self::response::work::{
312    Affiliation, Agency, Assertion, AssertionGroup, ClinicalTrialNumber, ContentDomain,
313    Contributor, Date, DateField, DateParts, Explanation, FundingBody, ISSN, InstitutionId, Issue,
314    License, PartialDate, Reference, RelatedItems, Relation, Relations, ResourceLink, Review,
315    Update,
316};
317
318pub(crate) use self::response::{Message, Response};
319
320/// The async iterator trait implemented by [`WorkListIterator`].
321///
322/// Re-exported so callers can drive deep paging without depending on
323/// `async-iterator` directly.
324pub use async_iterator::Iterator as AsyncIterator;
325
326use crate::limit::{Limiter, retry_after};
327use crate::response::Prefix;
328use reqwest::{Client, StatusCode};
329use std::sync::Arc;
330
331/// Unwraps the payload a route is expected to answer with, or reports what
332/// crossref sent instead.
333macro_rules! get_item {
334    ($ident:ident, $response:expr) => {{
335        let response = $response;
336        match response.message {
337            Message::$ident(item) => Ok(item),
338            other => Err(Error::UnexpectedItem {
339                expected: MessageType::$ident,
340                got: other.message_type(),
341            }),
342        }
343    }};
344}
345
346macro_rules! impl_combined_works_query {
347    ($($name:ident  $component:ident,)*) => {
348        $(
349        /// Return one page of the components's `Work` that match the query
350        ///
351        pub async fn $name(&self, ident: WorksIdentQuery) -> Result<WorkList> {
352            let resp = self.get_response(&$component::Works(ident)).await?;
353            get_item!(WorkList, resp)
354        })+
355    };
356}
357
358/// The bare body crossref answers a content-negotiation request it cannot
359/// serve with, which is shaped nothing like a `validation-failure`.
360#[derive(serde::Deserialize)]
361struct TransformFailure {
362    /// what went wrong, e.g. `style-not-found`
363    code: String,
364    /// the DOI that was asked for
365    doi: Option<String>,
366    /// the explanation, e.g. `Style [vancouver] does not exist`
367    message: String,
368}
369
370/// Struct for Crossref search API methods
371///
372/// Cloning is cheap and shares the connection pool and the rate limiter, so
373/// concurrent callers should clone one client rather than build several -- see
374/// [`Crossref::rate_limit`].
375#[derive(Debug, Clone)]
376pub struct Crossref {
377    /// use another base url than `api.crossref.org`
378    base_url: String,
379    /// the reqwest client that handles the requests
380    client: Client,
381    /// paces requests against the budget crossref grants, shared between clones
382    limiter: Arc<Limiter>,
383    /// how many times a `429` is retried before giving up
384    max_retries: u32,
385}
386
387impl Crossref {
388    const BASE_URL: &'static str = "https://api.crossref.org";
389
390    /// Constructs a new `CrossrefBuilder`.
391    ///
392    /// This is the same as `Crossref::builder()`.
393    pub fn builder() -> CrossrefBuilder {
394        CrossrefBuilder::new()
395    }
396
397    /// The url every route is appended to, `https://api.crossref.org` unless
398    /// [`CrossrefBuilder::base_url`] said otherwise.
399    pub fn base_url(&self) -> &str {
400        &self.base_url
401    }
402
403    /// The request budget crossref last reported for this client.
404    ///
405    /// Crossref sends the budget on every response and the client paces itself
406    /// against it, so before the first request this is the assumed
407    /// [`RateLimit::CONSERVATIVE`] (or whatever [`CrossrefBuilder::rate_limit`]
408    /// was given) and afterwards it is what crossref actually granted.
409    pub fn rate_limit(&self) -> RateLimit {
410        self.limiter.rate()
411    }
412
413    /// The pool crossref sorted the last request into, from `x-api-pool`.
414    ///
415    /// `polite` if [`CrossrefBuilder::polite`] worked, `plus` for a Plus token,
416    /// otherwise `public`. [`None`] before the first request.
417    pub fn api_pool(&self) -> Option<String> {
418        self.limiter.pool()
419    }
420
421    // generate all functions to query combined endpoints
422    impl_combined_works_query!(funder_works Funders, member_works Members,
423    type_works Types, journal_works Journals, prefix_works Prefixes,);
424
425    /// Transforms the `CrossrefQuery` in the request route and  executes the request
426    ///
427    /// # Errors
428    ///
429    /// If crossref could not resolve the route, a `ResourceNotFound` error is returned.
430    /// Also fails if the json response body could not be parsed into `Response`.
431    /// Fails if there was an error in reqwest executing the request [::reqwest::RequestBuilder::send]
432    async fn get_response<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
433        let url = query.to_url(&self.base_url)?;
434        let response = self.send(&url).await?;
435
436        // crossref answers an unresolvable route with a plain-text body, which
437        // would otherwise surface as an opaque deserialization failure
438        if response.status() == StatusCode::NOT_FOUND {
439            return Err(Error::ResourceNotFound {
440                resource: Box::new(query.clone().resource_component()),
441            });
442        }
443
444        // deserialized here rather than through `reqwest`'s `json()` so a
445        // shape crossref changed surfaces as `Error::Serde`, which names the
446        // field that failed
447        let body = Self::into_success(response).await?.bytes().await?;
448        serde_json::from_slice(&body).map_err(|error| Error::Serde { error })
449    }
450
451    /// Sends a `GET`, pacing it against the rate limit and retrying a `429`.
452    ///
453    /// Waits for a slot from the shared [`Limiter`] first, then feeds the
454    /// budget crossref reports back into it. A `429` means the budget we
455    /// believed in was wrong, so the whole client backs off -- for as long as
456    /// `retry-after` asks, or exponentially from the reported interval -- and
457    /// the request is sent again up to [`CrossrefBuilder::max_retries`] times.
458    async fn send(&self, url: &str) -> Result<reqwest::Response> {
459        self.send_with(url, |request| request).await
460    }
461
462    /// [`Crossref::send`], with `customize` applied to the request first.
463    async fn send_with(
464        &self,
465        url: &str,
466        customize: impl Fn(reqwest::RequestBuilder) -> reqwest::RequestBuilder,
467    ) -> Result<reqwest::Response> {
468        let mut attempt = 0u32;
469        loop {
470            self.limiter.acquire().await;
471            tracing::debug!(%url, attempt, "crossref request");
472
473            let response = customize(self.client.get(url)).send().await?;
474            self.limiter.observe(response.headers());
475
476            if response.status() != StatusCode::TOO_MANY_REQUESTS {
477                return Ok(response);
478            }
479
480            let limit = self.limiter.rate();
481            let delay = retry_after(response.headers())
482                .unwrap_or_else(|| limit.interval * 2u32.pow(attempt.min(5)));
483            self.limiter.back_off(delay);
484            attempt += 1;
485
486            if attempt > self.max_retries {
487                tracing::warn!(%url, attempt, "crossref rate limited, retries exhausted");
488                return Err(Error::RateLimited {
489                    attempts: attempt,
490                    limit,
491                });
492            }
493            tracing::debug!(%url, attempt, ?delay, "crossref rate limited, retrying");
494        }
495    }
496
497    /// Turns a non-success response into the error crossref described.
498    ///
499    /// Crossref answers a bad filter, sort field or field query with a `400`
500    /// and a `validation-failure` body naming what it did not recognise, and an
501    /// unservable content-negotiation format with a `406` and a bare
502    /// `{code, message}` -- both of which
503    /// [`reqwest::Response::error_for_status`] would throw away.
504    async fn into_success(response: reqwest::Response) -> Result<reqwest::Response> {
505        if response.status().is_success() {
506            return Ok(response);
507        }
508
509        // taken before the body is consumed, so the status is still reportable
510        // if the body turns out not to explain itself
511        let status = response.error_for_status_ref().expect_err("not a success");
512        let body = response.text().await.unwrap_or_default();
513
514        if let Ok(Response {
515            message: Message::ValidationFailure(failures),
516            ..
517        }) = serde_json::from_str::<Response>(&body)
518        {
519            return Err(Error::ValidationFailure { failures });
520        }
521        if let Ok(failure) = serde_json::from_str::<TransformFailure>(&body) {
522            return Err(Error::ValidationFailure {
523                failures: vec![Failure {
524                    type_: failure.code,
525                    value: failure.doi.unwrap_or_default(),
526                    message: failure.message,
527                }]
528                .into(),
529            });
530        }
531        Err(status.into())
532    }
533
534    //fn get_response_blocking<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
535    //    let resp = self
536    //        .blocking_client
537    //        .get(&query.to_url(&self.base_url)?)
538    //        .send()?
539    //        .text()?;
540    //    if resp.starts_with("Resource not found") {
541    //        Err(Error::ResourceNotFound {
542    //            resource: Box::new(query.clone().resource_component()),
543    //        }
544    //        .into())
545    //    } else {
546    //        Ok(serde_json::from_str(&resp)?)
547    //    }
548    //}
549
550    /// Return the `Work` items that match a certain query.
551    ///
552    /// To search only by query terms use the convenience query method [`Crossref::works`]
553    ///
554    /// # Example
555    ///
556    /// ```no_run
557    /// use crossref_client::{Crossref, WorksQuery, WorksFilter, FieldQuery};
558    /// # async fn run() -> Result<(), crossref_client::Error> {
559    /// let client = Crossref::builder().build()?;
560    ///
561    /// let query = WorksQuery::new("Machine Learning")
562    ///     .filter(WorksFilter::HasOrcid)
563    ///     .order(crossref_client::Order::Asc)
564    ///     .field_query(FieldQuery::author("Some Author"))
565    ///     .sort(crossref_client::Sort::Score);
566    ///
567    /// let works = client.works(query).await?;
568    ///
569    /// # Ok(())
570    /// # }
571    /// ```
572    ///
573    /// # Errors
574    ///
575    /// This method fails if the `works` element expands to a bad route `ResourceNotFound`
576    /// Fails if the response body doesn't have `message` field `MissingMessage`.
577    /// Fails if anything else than a `WorkList` is returned as message `UnexpectedItem`
578    pub async fn works<T: Into<WorkListQuery>>(&self, query: T) -> Result<WorkList> {
579        let resp = self.get_response(&query.into()).await?;
580
581        get_item!(WorkList, resp)
582    }
583
584    /// Return the `Work` that is identified by  the `doi`.
585    ///
586    /// # Errors
587    /// This method fails if the doi could not identified `ResourceNotFound`
588    ///
589    pub async fn work(&self, doi: &str) -> Result<Work> {
590        let resp = self
591            .get_response(&Works::Identifier(doi.to_string()))
592            .await?;
593        get_item!(Work, resp).map(|x| *x)
594    }
595
596    /// [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
597    /// Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
598    /// This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
599    /// Usually a single page `WorkList` contains 20 items.
600    ///
601    /// # Example
602    ///
603    /// Iterate over all `Works` linked to search term `Machine Learning`
604    ///
605    /// ```no_run
606    /// use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
607    /// # async fn run() -> Result<(), crossref_client::Error> {
608    /// let client = Crossref::builder().build()?;
609    ///
610    /// let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
611    /// let mut all_works: Vec<Work> = Vec::new();
612    /// while let Some(page) = pages.next().await {
613    ///     let page = page?;
614    ///     all_works.extend(page.items);
615    /// }
616    ///
617    /// # Ok(())
618    /// # }
619    /// ```
620    ///
621    /// # Example
622    ///
623    /// Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
624    /// A single `WorkList` usually holds 20 `Work` items.
625    ///
626    /// ```no_run
627    /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
628    /// # async fn run() -> Result<(), crossref_client::Error> {
629    /// let client = Crossref::builder().build()?;
630    ///
631    /// let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
632    /// let mut all_funder_work_list: Vec<WorkList> = Vec::new();
633    /// while let Some(page) = pages.next().await {
634    ///     let page = page?;
635    ///     all_funder_work_list.push(page);
636    /// }
637    ///
638    /// # Ok(())
639    /// # }
640    /// ```
641    /// # Example
642    ///
643    /// Iterate over all `Work` items of a specfic funder directly.
644    ///
645    /// ```no_run
646    /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
647    /// # async fn run() -> Result<(), crossref_client::Error> {
648    /// let client = Crossref::builder().build()?;
649    ///
650    /// let mut works = client.deep_page(WorksQuery::default()
651    ///         .into_combined_query::<Funders>("funder id"))
652    ///         .into_work_iter();
653    /// let mut all_works: Vec<Work> = Vec::new();
654    /// while let Some(work) = works.next().await {
655    ///     let work = work?;
656    ///     all_works.push(work);
657    /// }
658    ///
659    /// # Ok(())
660    /// # }
661    /// ```
662    ///
663    /// # Example
664    ///
665    /// Alternatively deep page without an iterator by handling the cursor directly
666    ///
667    /// ```no_run
668    /// use crossref_client::{Crossref, WorksQuery, WorksFilter};
669    /// # async fn run() -> Result<(), crossref_client::Error> {
670    /// let client = Crossref::builder().build()?;
671    ///
672    /// // request a next-cursor first
673    /// let query = WorksQuery::new("Machine Learning")
674    ///     .new_cursor();
675    ///
676    /// let works = client.works(query.clone()).await?;
677    ///
678    /// // this continues from where this first response stopped
679    /// // if no more work items are available then a empty list will be returned
680    /// let deep_works = client.works(
681    ///     query.next_cursor(&works.next_cursor.unwrap())
682    /// ).await?;
683    /// # Ok(())
684    /// # }
685    /// ```
686    ///
687    pub fn deep_page<T: Into<WorkListQuery>>(&self, query: T) -> WorkListIterator<'_> {
688        WorkListIterator::new(query.into(), self)
689    }
690
691    /// Re-serialize the work identified by `doi` into another format.
692    ///
693    /// Crossref renders the registered metadata itself, so this never goes
694    /// through [`Work`] and the body is returned verbatim -- BibTeX, RIS, RDF
695    /// or a citation formatted in a [CSL style](Crossref::styles).
696    ///
697    /// # Example
698    ///
699    /// ```no_run
700    /// use crossref_client::{CnFormat, Crossref};
701    /// # async fn run() -> Result<(), crossref_client::Error> {
702    /// # let client = Crossref::builder().build()?;
703    /// let bibtex = client
704    ///     .transform("10.1037/0003-066X.59.1.29", &CnFormat::BibTex)
705    ///     .await?;
706    ///
707    /// let citation = client
708    ///     .transform("10.1037/0003-066X.59.1.29", &CnFormat::bibliography("apa"))
709    ///     .await?;
710    /// # Ok(())
711    /// # }
712    /// ```
713    ///
714    /// # Errors
715    ///
716    /// Fails with [`Error::ValidationFailure`] if crossref cannot serve the
717    /// format for this DOI -- an unknown CSL style is the usual cause.
718    pub async fn transform(&self, doi: &str, format: &CnFormat) -> Result<String> {
719        let url = format!("{}/works/{}/transform", self.base_url, doi);
720        let response = self
721            .send_with(&url, |request| {
722                request.header(reqwest::header::ACCEPT, format.accept().as_ref())
723            })
724            .await?;
725
726        Ok(Self::into_success(response).await?.text().await?)
727    }
728
729    /// Return the [CSL styles](https://citationstyles.org) crossref can render
730    /// a citation in, for [`CnFormat::Bibliography`].
731    ///
732    /// Roughly 2 900 of them, in one response.
733    pub async fn styles(&self) -> Result<StyleList> {
734        let response = self.send(&format!("{}/styles", self.base_url)).await?;
735        let body = Self::into_success(response).await?.bytes().await?;
736        let response: Response =
737            serde_json::from_slice(&body).map_err(|error| Error::Serde { error })?;
738
739        get_item!(StyleList, response)
740    }
741
742    /// Return the `Agency` that registers the `Work` identified by  the `doi`.
743    ///
744    /// # Errors
745    /// This method fails if the doi could not identified `ResourceNotFound`
746    ///
747    pub async fn work_agency(&self, doi: &str) -> Result<WorkAgency> {
748        let resp = self.get_response(&Works::Agency(doi.to_string())).await?;
749        get_item!(WorkAgency, resp)
750    }
751
752    /// Return the matching `Funders` items.
753    pub async fn funders(&self, funders: FundersQuery) -> Result<FunderList> {
754        let resp = self.get_response(&Funders::Query(funders)).await?;
755        get_item!(FunderList, resp)
756    }
757
758    /// Return the `Funder` for the `id`
759    pub async fn funder(&self, id: &str) -> Result<Funder> {
760        let resp = self
761            .get_response(&Funders::Identifier(id.to_string()))
762            .await?;
763        get_item!(Funder, resp).map(|x| *x)
764    }
765
766    /// Return the matching `Members` items.
767    pub async fn members(&self, members: MembersQuery) -> Result<MemberList> {
768        let resp = self.get_response(&Members::Query(members)).await?;
769        get_item!(MemberList, resp)
770    }
771
772    /// Return the `Member` for the `id`
773    pub async fn member(&self, member_id: &str) -> Result<Member> {
774        let resp = self
775            .get_response(&Members::Identifier(member_id.to_string()))
776            .await?;
777        get_item!(Member, resp).map(|x| *x)
778    }
779
780    /// Return the `Prefix` for the `id`
781    pub async fn prefix(&self, id: &str) -> Result<Prefix> {
782        let resp = self
783            .get_response(&Prefixes::Identifier(id.to_string()))
784            .await?;
785        get_item!(Prefix, resp)
786    }
787    /// Return a specific `Journal`
788    pub async fn journal(&self, id: &str) -> Result<Journal> {
789        let resp = self
790            .get_response(&Journals::Identifier(id.to_string()))
791            .await?;
792
793        get_item!(Journal, resp).map(|x| *x)
794    }
795
796    /// Return the matching `Journal` items.
797    ///
798    /// # Example
799    ///
800    /// ```no_run
801    /// use crossref_client::{Crossref, JournalsQuery, ResultControl};
802    /// # async fn run() -> Result<(), crossref_client::Error> {
803    /// # let client = Crossref::builder().build()?;
804    /// let journals = client
805    ///     .journals(JournalsQuery::new("Economic Geography").result_control(ResultControl::Rows(10)))
806    ///     .await?;
807    /// # Ok(())
808    /// # }
809    /// ```
810    pub async fn journals(&self, journals: JournalsQuery) -> Result<JournalList> {
811        let resp = self.get_response(&Journals::Query(journals)).await?;
812        get_item!(JournalList, resp)
813    }
814
815    /// Return the licenses works in the crossref metadata are published under,
816    /// each with the number of works that carry it.
817    ///
818    /// # Example
819    ///
820    /// ```no_run
821    /// use crossref_client::{Crossref, LicensesQuery, ResultControl};
822    /// # async fn run() -> Result<(), crossref_client::Error> {
823    /// # let client = Crossref::builder().build()?;
824    /// let licenses = client
825    ///     .licenses(LicensesQuery::new("creative commons").result_control(ResultControl::Rows(10)))
826    ///     .await?;
827    ///
828    /// for license in &licenses.items {
829    ///     println!("{:>8} {}", license.work_count, license.url);
830    /// }
831    /// # Ok(())
832    /// # }
833    /// ```
834    pub async fn licenses(&self, licenses: LicensesQuery) -> Result<LicenseList> {
835        let resp = self.get_response(&Licenses::Query(licenses)).await?;
836        get_item!(LicenseList, resp)
837    }
838
839    /// Return all available `Type`
840    pub async fn types(&self) -> Result<TypeList> {
841        let resp = self.get_response(&Types::All).await?;
842        get_item!(TypeList, resp)
843    }
844
845    /// Return the `Type` for the `id`
846    pub async fn type_(&self, id: &Type) -> Result<CrossrefType> {
847        let resp = self
848            .get_response(&Types::Identifier(id.id().to_string()))
849            .await?;
850        get_item!(Type, resp)
851    }
852
853    /// Get a random set of DOIs
854    ///
855    /// # Example
856    ///
857    /// ```no_run
858    /// use crossref_client::Crossref;
859    /// # async fn run() -> Result<(), crossref_client::Error> {
860    /// # let client = Crossref::builder().build()?;
861    /// // this will return 10 random dois from the crossref api
862    /// let random_dois = client.random_dois(10).await?;
863    /// # Ok(())
864    /// # }
865    /// ```
866    pub async fn random_dois(&self, len: usize) -> Result<Vec<String>> {
867        self.works(WorksQuery::random(len))
868            .await
869            .map(|x| x.items.into_iter().map(|x| x.doi).collect())
870    }
871}
872
873/// A `CrossrefBuilder` can be used to create `Crossref` with additional config.
874///
875/// # Example
876///
877/// ```no_run
878/// use crossref_client::Crossref;
879/// # async fn run() -> Result<(), crossref_client::Error> {
880///
881/// let client = Crossref::builder()
882///     .polite("polite@example.com")
883///     .token("your token")
884///     .build()?;
885/// # Ok(())
886/// # }
887/// ```
888/// Every setter accepts `Option`, so options that are themselves optional --
889/// a CLI flag, a config field -- can be passed straight through:
890///
891/// ```no_run
892/// # use crossref_client::Crossref;
893/// # fn run(email: Option<String>) -> Result<(), crossref_client::Error> {
894/// let client = Crossref::builder().polite(email.as_deref()).build()?;
895/// # Ok(())
896/// # }
897/// ```
898#[derive(Debug, Default)]
899pub struct CrossrefBuilder {
900    /// [Good manners = more reliable service.](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
901    ///
902    /// will add a `User-Agent` header by default with with the `email` email.
903    /// crossref can contact you if your script misbehaves
904    /// this will get you directed to the "polite pool"
905    user_agent: Option<String>,
906    /// the token for the Crossref Plus service will be included as `Authorization` header
907    /// This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
908    plus_token: Option<String>,
909    /// use a different base url than `Crossref::BASE_URL` <https://api.crossref.org>
910    base_url: Option<String>,
911    /// the budget to assume until crossref reports one
912    rate_limit: Option<RateLimit>,
913    /// how many times a `429` is retried
914    max_retries: Option<u32>,
915}
916
917impl CrossrefBuilder {
918    /// How many times a `429` is retried before [`Error::RateLimited`] is
919    /// returned, when the builder was not told otherwise.
920    const DEFAULT_MAX_RETRIES: u32 = 3;
921
922    /// Constructs a new `CrossrefBuilder`.
923    ///
924    /// This is the same as `Crossref::builder()`.
925    pub fn new() -> CrossrefBuilder {
926        CrossrefBuilder::default()
927    }
928
929    /// Be polite: identify yourself by email and get routed to crossref's
930    /// [polite pool](https://api.crossref.org/swagger-ui/index.html#/Etiquette).
931    ///
932    /// Sends a `User-Agent` in the shape crossref asks for, e.g.
933    /// `crossref-client/0.2.0 (https://github.com/…; mailto:you@example.com)`.
934    /// Anonymous requests share a rate-limited pool and are the usual cause of
935    /// `429` responses; check where you landed with
936    /// [`Crossref::api_pool`].
937    ///
938    /// Use [`CrossrefBuilder::user_agent`] instead if you want to send your own
939    /// application's name; include `mailto:<email>` in it to stay in the pool.
940    pub fn polite<'a>(mut self, email: impl Into<Option<&'a str>>) -> Self {
941        if let Some(email) = email.into() {
942            self.user_agent = Some(format!(
943                "{}/{} ({}; mailto:{})",
944                env!("CARGO_PKG_NAME"),
945                env!("CARGO_PKG_VERSION"),
946                env!("CARGO_PKG_REPOSITORY"),
947                email
948            ));
949        }
950        self
951    }
952
953    /// set the user agent directly
954    pub fn user_agent<'a>(mut self, user_agent: impl Into<Option<&'a str>>) -> Self {
955        self.user_agent = user_agent.into().map(str::to_owned);
956        self
957    }
958
959    /// set a crossref plus service  API token
960    pub fn token<'a>(mut self, token: impl Into<Option<&'a str>>) -> Self {
961        self.plus_token = token.into().map(str::to_owned);
962        self
963    }
964
965    /// Send requests somewhere other than `https://api.crossref.org`.
966    ///
967    /// Routes are appended verbatim, so the url must not end in a `/`. Mainly
968    /// useful for pointing the client at a mock or a proxy in tests.
969    pub fn base_url<'a>(mut self, base_url: impl Into<Option<&'a str>>) -> Self {
970        self.base_url = base_url.into().map(str::to_owned);
971        self
972    }
973
974    /// The request budget to assume until crossref reports its own.
975    ///
976    /// Defaults to [`RateLimit::CONSERVATIVE`]. Crossref sends the real budget
977    /// on every response and the client follows it from then on, so this only
978    /// paces the first few requests.
979    pub fn rate_limit(mut self, rate_limit: impl Into<Option<RateLimit>>) -> Self {
980        self.rate_limit = rate_limit.into();
981        self
982    }
983
984    /// How many times a `429` is retried before giving up with
985    /// [`Error::RateLimited`]. Defaults to 3; `0` disables retrying.
986    pub fn max_retries(mut self, max_retries: impl Into<Option<u32>>) -> Self {
987        self.max_retries = max_retries.into();
988        self
989    }
990
991    /// Returns a `Crossref` that uses this `CrossrefBuilder` configuration.
992    /// # Errors
993    ///
994    /// This will fail if TLS backend cannot be initialized see [reqwest::ClientBuilder::build]
995    pub fn build(self) -> Result<Crossref> {
996        use reqwest::header;
997        let mut headers = header::HeaderMap::new();
998        if let Some(agent) = &self.user_agent {
999            headers.insert(
1000                header::USER_AGENT,
1001                header::HeaderValue::from_str(agent).map_err(|_| Error::Config {
1002                    msg: format!("failed to create User Agent header for `{}`", agent),
1003                })?,
1004            );
1005        }
1006        if let Some(token) = &self.plus_token {
1007            headers.insert(
1008                header::AUTHORIZATION,
1009                header::HeaderValue::from_str(token).map_err(|_| Error::Config {
1010                    msg: format!("failed to create AUTHORIZATION header for `{}`", token),
1011                })?,
1012            );
1013        }
1014        let client = reqwest::Client::builder()
1015            .default_headers(headers)
1016            .build()
1017            .map_err(|_| Error::Config {
1018                msg: "failed to initialize TLS backend".to_string(),
1019            })?;
1020
1021        Ok(Crossref {
1022            base_url: self
1023                .base_url
1024                .unwrap_or_else(|| Crossref::BASE_URL.to_string()),
1025            client,
1026            limiter: Arc::new(Limiter::new(self.rate_limit.unwrap_or_default())),
1027            max_retries: self.max_retries.unwrap_or(Self::DEFAULT_MAX_RETRIES),
1028        })
1029    }
1030}
1031
1032/// Allows iterating of deep page work request
1033pub struct WorkListIterator<'a> {
1034    /// the query
1035    query: WorkListQuery,
1036    /// performs each request
1037    client: &'a Crossref,
1038    /// whether the iterator should finish next iteration
1039    finish_next_iteration: bool,
1040}
1041
1042impl<'a> WorkListIterator<'a> {
1043    /// Create an iterator that deep pages `query` through `client`.
1044    pub fn new(query: WorkListQuery, client: &'a Crossref) -> Self {
1045        Self {
1046            query,
1047            client,
1048            finish_next_iteration: false,
1049        }
1050    }
1051
1052    /// Flatten the paged results into an iterator over individual [`Work`] items.
1053    ///
1054    /// Pages are fetched lazily, one request at a time, as the buffer drains.
1055    pub fn into_work_iter(self) -> WorkIterator<'a> {
1056        WorkIterator {
1057            pages: self,
1058            buffer: Vec::new().into_iter(),
1059        }
1060    }
1061}
1062
1063/// Yields individual [`Work`] items across the deep paged [`WorkList`] pages.
1064///
1065/// Created by [`WorkListIterator::into_work_iter`].
1066pub struct WorkIterator<'a> {
1067    pages: WorkListIterator<'a>,
1068    buffer: std::vec::IntoIter<Work>,
1069}
1070
1071impl async_iterator::Iterator for WorkIterator<'_> {
1072    type Item = Result<Work>;
1073
1074    async fn next(&mut self) -> Option<Self::Item> {
1075        loop {
1076            if let Some(work) = self.buffer.next() {
1077                return Some(Ok(work));
1078            }
1079            // `WorkListIterator` stops on the first empty page and after an
1080            // error, so this terminates
1081            match self.pages.next().await? {
1082                Ok(page) => self.buffer = page.items.into_iter(),
1083                Err(err) => return Some(Err(err)),
1084            }
1085        }
1086    }
1087}
1088
1089impl async_iterator::Iterator for WorkListIterator<'_> {
1090    type Item = Result<WorkList>;
1091
1092    async fn next(&mut self) -> Option<Self::Item> {
1093        if self.finish_next_iteration {
1094            return None;
1095        }
1096
1097        {
1098            let control = &mut self.query.query_mut().result_control;
1099
1100            // if no result control is set, set a new cursor
1101            if control.is_none() {
1102                *control = Some(WorkResultControl::new_cursor());
1103            }
1104        }
1105
1106        let page = match self.client.get_response(&self.query).await {
1107            Ok(resp) => get_item!(WorkList, resp),
1108            Err(err) => Err(err),
1109        };
1110
1111        let worklist = match page {
1112            Ok(worklist) => worklist,
1113            Err(err) => {
1114                // a transient `429` or an unparsable page used to end the
1115                // iteration silently, which a caller cannot tell apart from
1116                // having crawled everything -- surface it and stop
1117                self.finish_next_iteration = true;
1118                return Some(Err(err));
1119            }
1120        };
1121
1122        if let Some(cursor) = &worklist.next_cursor {
1123            match &mut self.query.query_mut().result_control {
1124                Some(WorkResultControl::Cursor { token, .. }) => {
1125                    // use the received cursor token in next iteration
1126                    *token = Some(cursor.clone())
1127                }
1128                Some(WorkResultControl::Standard(_)) => {
1129                    // standard result control was set, don't deep page and return next iteration
1130                    self.finish_next_iteration = true;
1131                }
1132                _ => (),
1133            }
1134        } else {
1135            // no cursor received, end next iteration
1136            self.finish_next_iteration = true;
1137        }
1138
1139        if worklist.items.is_empty() {
1140            None
1141        } else {
1142            Some(Ok(worklist))
1143        }
1144    }
1145}