marple_db/lib.rs
1//! Rust SDK for the MarpleDB API.
2//!
3//! The SDK provides async helpers for checking API health, managing streams,
4//! listing datasets, uploading files, waiting for imports, and fetching
5//! pre-signed download links.
6//!
7//! # Quickstart
8//!
9//! ```no_run
10//! use marple_db::{ImportStatus, MarpleDB, PushFileOptions};
11//! use serde_json::json;
12//! use std::time::Duration;
13//!
14//! # async fn run() -> marple_db::Result<()> {
15//! let db = MarpleDB::new(
16//! "https://db.marpledata.com/api/v1",
17//! "mdb_your_token_here",
18//! )?;
19//! let stream = db.get_stream("runs").await?;
20//! let dataset = db
21//! .push_file(
22//! stream.id,
23//! "run.csv",
24//! PushFileOptions::builder()
25//! .metadata([("source", json!("example"))])
26//! .build(),
27//! )
28//! .await?;
29//! let dataset = db
30//! .wait_for_import(stream.id, dataset.id, Duration::from_secs(180))
31//! .await?;
32//! assert_eq!(dataset.import_status, ImportStatus::Finished);
33//! # Ok(())
34//! # }
35//! ```
36//!
37//! # Core Types
38//!
39//! - [`MarpleDB`] is the API client.
40//! - [`PushFileOptions`] configures uploads.
41//! - [`ImportStatus`] describes dataset import state.
42//! - [`Error`] is the structured SDK error type.
43//! - [`ProgressReporter`] receives transfer progress updates.
44//!
45//! # Errors
46//!
47//! ```no_run
48//! # async fn run(db: marple_db::MarpleDB) -> marple_db::Result<()> {
49//! match db.get_stream("runs").await {
50//! Ok(stream) => println!("stream id: {}", stream.id),
51//! Err(marple_db::Error::StreamNotFound { name }) => {
52//! eprintln!("missing stream: {name}");
53//! }
54//! Err(error) => return Err(error),
55//! }
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! This crate is async and does not install a runtime. The examples use Tokio,
61//! but callers can use any runtime supported by `reqwest`.
62
63mod client;
64mod errors;
65mod models;
66mod progress;
67mod upload;
68
69pub use client::{MarpleDB, MarpleDBBuilder};
70pub use errors::{Error, Result};
71pub use models::{
72 Dataset, HealthResponse, ImportStatus, Metadata, PushFileOptions, PushFileOptionsBuilder,
73 Stream, StreamType, UploadModeOverride,
74};
75pub use progress::{NoopProgress, ProgressReporter};