cdk-npubcash 0.17.7

CDK npubcash sdk
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

//! # NpubCash SDK
//!
//! Rust client SDK for the NpubCash v2 API.
//!
//! ## Features
//!
//! - HTTP client for fetching quotes with auto-pagination
//! - NIP-98 and JWT authentication
//! - User settings management
//!
//! ## Quick Start
//!
//! ```no_run
//! use std::sync::Arc;
//!
//! use cdk_npubcash::{JwtAuthProvider, NpubCashClient};
//! use nostr_sdk::Keys;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create authentication provider with Nostr keys
//!     let base_url = "https://npubx.cash".to_string();
//!     let keys = Keys::generate();
//!     let auth_provider = Arc::new(JwtAuthProvider::new(base_url.clone(), keys));
//!
//!     // Create the NpubCash client
//!     let client = NpubCashClient::new(base_url, auth_provider);
//!
//!     // Fetch all quotes
//!     let quotes = client.get_quotes(None).await?;
//!     println!("Found {} quotes", quotes.len());
//!
//!     // Fetch quotes since a specific timestamp
//!     let recent_quotes = client.get_quotes(Some(1234567890)).await?;
//!     println!("Found {} recent quotes", recent_quotes.len());
//!
//!     // Update mint URL setting
//!     client.set_mint_url("https://example-mint.tld").await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Authentication
//!
//! The SDK uses NIP-98 HTTP authentication for initial requests and JWT tokens
//! for subsequent requests. The [`JwtAuthProvider`] handles this automatically,
//! including token caching and refresh.
//!
//! ## Fetching Quotes
//!
//! ```no_run
//! # use cdk_npubcash::{NpubCashClient, JwtAuthProvider};
//! # use nostr_sdk::Keys;
//! # use std::sync::Arc;
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! # let base_url = "https://npubx.cash".to_string();
//! # let keys = Keys::generate();
//! # let auth_provider = Arc::new(JwtAuthProvider::new(base_url.clone(), keys));
//! # let client = NpubCashClient::new(base_url, auth_provider);
//! // Fetch all quotes
//! let all_quotes = client.get_quotes(None).await?;
//!
//! // Fetch quotes since a specific timestamp
//! let recent_quotes = client.get_quotes(Some(1234567890)).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Managing Settings
//!
//! ```no_run
//! # use cdk_npubcash::{NpubCashClient, JwtAuthProvider};
//! # use nostr_sdk::Keys;
//! # use std::sync::Arc;
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! # let base_url = "https://npubx.cash".to_string();
//! # let keys = Keys::generate();
//! # let auth_provider = Arc::new(JwtAuthProvider::new(base_url.clone(), keys));
//! # let client = NpubCashClient::new(base_url, auth_provider);
//! // Set mint URL
//! let response = client.set_mint_url("https://my-mint.com").await?;
//! println!("Mint URL: {:?}", response.data.user.mint_url);
//! println!("Lock quote: {}", response.data.user.lock_quote);
//! # Ok(())
//! # }
//! ```
//!
//! **Note:** Quotes are always locked by default on the NPubCash server for security.

#![warn(missing_docs)]
#![allow(clippy::doc_markdown)]

pub mod auth;
pub mod client;
pub mod error;
pub mod types;

// Re-export main types for convenient access
pub use auth::JwtAuthProvider;
pub use client::NpubCashClient;
pub use error::{Error, Result};
pub use types::{
    Metadata, Nip98Data, Nip98Response, Quote, QuotesData, QuotesResponse, UserData, UserResponse,
};

/// Extract authentication URL (scheme + host + path, no query params)
///
/// # Arguments
///
/// * `url` - The full URL to parse
///
/// # Errors
///
/// Returns an error if the URL is invalid or missing required components
pub(crate) fn extract_auth_url(url: &str) -> Result<String> {
    let parsed_url = url::Url::parse(url)?;
    let host = parsed_url
        .host_str()
        .ok_or_else(|| Error::Custom("Invalid URL: missing host".to_string()))?;

    Ok(format!(
        "{}://{}{}",
        parsed_url.scheme(),
        host,
        parsed_url.path()
    ))
}