ankiconnect_rs/lib.rs
1//! # ankiconnect-rs
2//!
3//! A Rust crate for interacting with [AnkiConnect](https://foosoft.net/projects/anki-connect/),
4//! enabling convenient programmatic control of Anki from within Rust.
5//! Provides type-safe abstractions for common Anki operations.
6//!
7//! ## Features
8//!
9//! - 🃏 **Card Management**: Create notes, find cards, browse cards via GUI
10//! - 🗃️ **Deck Operations**: Create decks, list existing decks
11//! - 📦 **Media Handling**: Store media files from paths/URLs/base64 data
12//! - 🧩 **Model Support**: Fetch field names, validate note structures
13//! - 🔄 **Error Handling**: Comprehensive error types for AnkiConnect-specific issues
14//! - ✅ **Tested**: Mock server integration tests for all major operations
15//!
16//! ## Example
17//!
18//! ```rust,no_run
19//! use ankiconnect_rs::{AnkiClient, NoteBuilder, Field, MediaSource};
20//! use std::error::Error;
21//!
22//! fn main() -> Result<(), Box<dyn Error>> {
23//! // Create a client with default connection (localhost:8765)
24//! let client = AnkiClient::new();
25//!
26//! // Get available decks and models
27//! let decks = client.decks().get_all()?;
28//! let models = client.models().get_all()?;
29//!
30//! // Get fields for the selected model
31//! let selected_model = &models[0];
32//! let fields = client.models().get_fields(selected_model)?;
33//!
34//! // Build a note with the selected model
35//! let front_field = selected_model.field_ref("Front").unwrap();
36//! let back_field = selected_model.field_ref("Back").unwrap();
37//!
38//! let note = NoteBuilder::new(selected_model.clone())
39//! .with_field(front_field, "¿Dónde está la biblioteca?")
40//! .with_field(back_field, "Where is the library?")
41//! .with_tag("spanish-vocab")
42//! .with_image(
43//! front_field,
44//! MediaSource::Url("https://cdn.pixabay.com/photo/2023/08/18/15/02/dog-8198719_640.jpg".to_string()),
45//! "test_dog.jpg"
46//! )
47//! .build()?;
48//!
49//! // Add the note to the first deck
50//! let note_id = client.cards().add_note(&decks[0], note, false, None)?;
51//! println!("Added note with ID: {}", note_id.value());
52//!
53//! Ok(())
54//! }
55//! ```
56
57// Re-export key types for a clean public API
58pub use builders::{NoteBuilder, QueryBuilder};
59pub use client::{AnkiClient, DuplicateScope};
60pub use error::{AnkiConnectError, AnkiError, NoteError, Result};
61pub use models::{
62 Card, CardId, Deck, DeckId, Field, FieldMedia, Media, MediaSource, MediaType, Model, Note,
63 NoteId,
64};
65
66// Public modules
67pub mod builders;
68pub mod client;
69pub mod error;
70pub mod models;
71
72// Private modules
73mod http;