librus-rs

Rust client for Librus Synergia - the Polish school diary system.

Installation

Add to your Cargo.toml:

[dependencies]
librus-rs = "2.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use librus_rs::Client;

#[tokio::main]
async fn main() -> Result<(), librus_rs::Error> {
    // From environment variables (LIBRUS_USERNAME, LIBRUS_PASSWORD)
    let mut client = Client::from_env().await?;

    // Fetch grades
    let grades = client.grades().await?;
    for grade in grades.grades {
        println!("{}: {}", grade.date, grade.grade);
    }

    // Fetch messages
    let unread = client.unread_counts().await?;
    println!("Unread messages: {}", unread.inbox);

    let messages = client.inbox_messages(1, 10).await?;
    for msg in messages {
        println!("{}: {}", msg.sender_name, msg.topic);
    }

    // Fetch school notices (announcements)
    let notices = client.school_notices_latest(10).await?;
    for notice in notices {
        let content = Client::notice_content_to_text(&notice.content);
        let preview: String = content.chars().take(80).collect();
        println!("{}: {}", notice.subject, preview);
    }

    Ok(())
}

Client Construction

Three ways to create a client:

use librus_rs::Client;

// From environment variables
let client = Client::from_env().await?;

// With explicit credentials
let client = Client::new("username", "password").await?;

// Using the builder pattern
let client = Client::builder()
    .username("username")
    .password("password")
    .build()
    .await?;

API Reference

Synergia API

Base URL: https://synergia.librus.pl/gateway/api/2.0/

Method	Description
`me()`	Get current user info
`grades()`	Get all grades
`grade_category(id)`	Get grade category by ID
`grade_comment(id)`	Get grade comment by ID
`lesson(id)`	Get lesson info by ID
`subject(id)`	Get subject info by ID
`attendances()`	Get all attendances
`attendance_types()`	Get attendance types
`homeworks()`	Get all homeworks
`school_notices()`	Get school notices (announcements)
`school_notices_page(page, limit)`	Get school notices with pagination
`school_notices_latest(limit)`	Get latest notices (client-side sort)
`user(id)`	Get user by ID
`current_user()`	Get current user details

Notes:

Pagination is supported by SchoolNotices (via page/limit query params).

Messages API

Base URL: https://wiadomosci.librus.pl/api/

Method	Description
`unread_counts()`	Get unread message counts for all folders
`inbox_messages(page, limit)`	List received messages
`outbox_messages(page, limit)`	List sent messages
`message(id)`	Get full message details
`attachment(attachment_id, message_id)`	Download attachment as bytes
`decode_message_content(base64)`	Decode base64 message content to string
`notice_content_to_text(html)`	Convert API-provided notice HTML to text

API Documentation

There is no official public documentation for the Synergia API. Community references:

https://libraries.io/go/github.com%2Fgoferwplynie%2FlibrusApi (lists implemented endpoints; notes lack of official docs)
https://ravensiris.github.io/librusapi/ (HTML-scraping docs; not official)

Error Handling

All methods return Result<T, librus_rs::Error>. Error variants:

pub enum Error {
    Authentication,                     // Invalid credentials
    MissingEnvVar(&'static str),        // Environment variable not set
    MissingCredentials(&'static str),   // Builder credential missing
    HttpClient(reqwest::Error),         // HTTP client error
    Request(reqwest::Error),            // Request failed
    ApiError { status, body },          // API returned error
    Parse { source, body },             // JSON parsing failed
}

Types

Key Exported Types

pub use librus_rs::{
    Client,         // Main API client
    Error,          // Error type

    // Grades
    Grade, GradeCategory, GradeComment,
    ResponseGrades, ResponseGradesCategories, ResponseGradesComments,

    // Lessons & Attendance
    Lesson, LessonSubject, Attendance, AttendanceType,
    ResponseLesson, ResponseLessonSubject, ResponseAttendances, ResponseAttendancesType,

    // User
    Me, User, ResponseMe, ResponseUser,

    // Homework
    Homework, ResponseHomeworks,

    // School notices (announcements)
    SchoolNotice, ResponseSchoolNotices,

    // Messages
    InboxMessage, OutboxMessage, MessageDetail, Attachment, UnreadCounts,
};

InboxMessage

pub struct InboxMessage {
    pub message_id: String,
    pub sender_first_name: String,
    pub sender_last_name: String,
    pub sender_name: String,
    pub topic: String,
    pub content: String,       // Base64 encoded
    pub send_date: String,
    pub read_date: Option<String>,
    pub is_any_file_attached: bool,
    pub tags: Vec<String>,
    pub category: Option<String>,
}

MessageDetail

pub struct MessageDetail {
    pub message_id: String,
    pub sender_id: Option<String>,
    pub sender_first_name: String,
    pub sender_last_name: String,
    pub sender_name: String,
    pub sender_group: Option<String>,
    pub topic: String,
    pub message: String,       // Base64 encoded
    pub send_date: String,
    pub read_date: Option<String>,
    pub attachments: Vec<Attachment>,
    pub receivers_count: Option<u32>,
    pub no_reply: Option<u8>,
    pub archive: Option<u8>,
}

Development

For Nix users:

nix develop
cargo build
cargo test

License

MIT

librus-rs 2.0.1