Staging

.gitignore

@@ -27,4 +27,5 @@ target
 Cargo.lock
 
 # Logs
-*.log
+*.log
+docs/vimstoat/book*/

Cargo.toml

@@ -18,12 +18,22 @@ pickledb = { version = "0.5.1", features = ["bincode"] }
 # Directories
 dirs = "6.0.0"
 
+# Notifications
+notify-rust = "4.18.0"
+# WebSockets
+tokio-tungstenite = { version = "0.30.0", features = ["native-tls"] }
+futures-util = "0.3.31"
+
 keyring-lib = { version = "1.0.3", features = ["tokio"] }
 ratatui = "0.30.2"
-reqwest = { version = "0.13.4", default-features = false, features = ["json"] }
+reqwest = { version = "0.13.4", default-features = false, features = [
+  "json",
+  "rustls",
+] }
 serde = { version = "1", features = ["derive"] }
 tokio = { version = "1.52.3", features = ["full"] }
 serde_json = "1.0.150"
+ulid = "3.0.0"
 
 [dev-dependencies]
 cargo-husky = { version = "1.5.0", default-features = false, features = [

README.md

@@ -2,7 +2,7 @@
 
 A lightweight TUI [Stoat](https://stoat.chat) client that feels like Vim.
 
-> **Status:** Early development — see [ROADMAP.md](ROADMAP.md) for the full plan.
+> **Status:** Early development — see our [Documentation](docs/vimstoat/src/SUMMARY.md) for features and keybinds.
 
 ## What is this?
 

docs/vimstoat/src/SUMMARY.md

@@ -1,3 +1,4 @@
 # Summary
 
+- [Features](./features.md)
 - [Keybinds](./keybinds.md)

docs/vimstoat/src/features.md

@@ -0,0 +1,20 @@
+# Features
+
+VimStoat is currently in early development. Here are the features implemented so far:
+
+## Real-time Messaging
+- **WebSocket Integration**: Listens for real-time `Message`, `MessageUpdate`, and `MessageDelete` events from the server.
+- **Dynamic Author Resolution**: Transparently fetches and caches unknown user profiles to display real usernames instead of raw IDs in the UI.
+- **In-Memory Cache**: Uses an in-memory cache synchronized to disk upon application exit for maximum performance.
+
+## Direct Messages
+- **DM List View**: Displays all active Direct Message channels.
+- **Unread Indicators**: Channels with new messages are automatically marked with a red `[*]` unread indicator.
+- **Message Previews**: The DM list shows a truncated preview of the latest message for each channel.
+- **Chat Interface**: View message history and send new messages seamlessly via the REST API.
+
+## Vim-Native Interface
+- **Mode-Specific UI Themes**: Border colors dynamically shift based on the current mode (e.g., Yellow for Insert mode, Blue for UI/Normal mode).
+- **Cursor Shaping**: Hardware cursor shape changes depending on mode (e.g., blinking bar in Insert mode, block in Normal mode).
+- **Input Motions**: Features robust vim-like text composition motions like `i`, `I`, `a`, `A`, `o`, `O`, `dd` (delete line), and an in-memory yank buffer.
+- **Screen Navigation**: Use `q` or `:q` to navigate back through screens, and `:qa` to quit globally.

docs/vimstoat/src/keybinds.md

@@ -19,11 +19,21 @@
 | `A`   | Enter Insert mode, at the end of the line                        |
 | `o`   | Enter Insert mode, and create a new line below the current line. |
 | `O`   | Enter Insert mode, and create a new line above the current line. |
+| `dd`  | Delete the current line                                          |
+| `gg`  | Go to the top of the UI list                                     |
+| `q`   | Go back or Quit                                                  |
 | `:`   | Enter Command mode                                               |
 | `/`   | Search (enters Command mode with `/` prefix)                     |
 | `v`   | Enter Visual mode (future)                                       |
 | `Esc` | Enter Normal mode                                                |
 
+## Commands (Command Mode)
+
+| Command        | Action                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `:q`, `:quit`  | Go back to the previous screen, or quit if at the top level      |
+| `:qa`, `:qall` | Quit the application immediately                                 |
+
 ## Fuzzy Finder
 
 | Key  | Action       |

src/action.rs

@@ -1,14 +1,24 @@
-/// Action based on user input
-#[derive(Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Action {
+    #[allow(unused)]
+    GoToTopUI,
     #[allow(unused)]
     AppendCharacter(char),
     RemoveCharacter,
+    EnterCommandMode,
+    EnterInsertMode,
+    EnterInsertModeAfter,
+    EnterInsertModeLineStart,
+    EnterInsertModeLineEnd,
+    OpenNewLineBelow,
+    OpenNewLineAbove,
+    DeleteLine,
     Enter,
     CursorLeft,
     CursorRight,
     CursorUp,
     CursorDown,
     Escape,
+    #[allow(unused)]
     Quit,
 }

src/api/auth.rs

@@ -1,4 +1,8 @@
-use crate::api::client::{ApiClient, Endpoint};
+use crate::{
+    Result,
+    api::client::{ApiClient, Endpoint},
+    error::AuthError,
+};
 use keyring::KeyringEntry;
 use serde_json::Value;
 
@@ -7,23 +11,21 @@ pub struct Auth {
 }
 
 impl Auth {
-    pub fn new() -> Result<Self, Box<dyn std::error::Error + Send + Sync>> {
+    pub fn new() -> Result<Self> {
         let crate_id = "vimstoat";
         let token_entry = KeyringEntry::try_new(crate_id)?;
         Ok(Self { token_entry })
     }
 
-    pub async fn store_token(&self, token: &str) -> Result<(), String> {
-        self.token_entry.set_secret(token).await.map_err(|e| {
-            format!(
-                "{}\n\nUnderlying Details:\n{:?}\n\n💡 Hint: If you are on a minimal Linux install, you likely need to install a Secret Service provider (e.g., `sudo pacman -S gnome-keyring`).",
-                e, e
-            )
-        })
+    pub async fn store_token(&self, token: &str) -> Result<()> {
+        self.token_entry
+            .set_secret(token)
+            .await
+            .map_err(|e| e.into())
     }
 
-    pub async fn validate_token(&self, token: &str) -> Result<ApiClient, String> {
-        let client = ApiClient::new(token.to_string());
+    pub async fn validate_token(&self, token: &str, base_url: Option<String>) -> Result<ApiClient> {
+        let client = ApiClient::new(token.to_string(), base_url);
 
         client
             .get::<Value>(Endpoint::CurrentUser)
@@ -32,9 +34,14 @@ impl Auth {
             .map_err(|e| {
                 let err_msg = e.to_string();
                 if err_msg.contains("401") {
-                    "Invalid token. Please check your session token and try again.".to_string()
+                    AuthError::InvalidToken(
+                        "Please check your session token and try again.".to_string(),
+                    )
+                    .into()
+                } else if err_msg.contains("API GET request") {
+                    AuthError::RequestError(err_msg).into()
                 } else {
-                    err_msg
+                    AuthError::ServerConnectionError.into()
                 }
             })
     }

src/api/channel.rs

@@ -0,0 +1,51 @@
+use crate::{
+    Result,
+    api::client::{ApiClient, Endpoint},
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct MessageHistoryQuery {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub before: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub after: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub nearby: Option<String>,
+}
+
+pub async fn fetch_message_history(
+    api_client: &ApiClient,
+    channel_id: &str,
+    query: Option<&MessageHistoryQuery>,
+) -> Result<Vec<serde_json::Value>> {
+    let mut path = format!("/channels/{}/messages", channel_id);
+    if let Some(q) = query {
+        let mut params = Vec::new();
+        if let Some(limit) = q.limit {
+            params.push(format!("limit={}", limit));
+        }
+        if let Some(before) = &q.before {
+            params.push(format!("before={}", before));
+        }
+        if let Some(after) = &q.after {
+            params.push(format!("after={}", after));
+        }
+        if let Some(sort) = &q.sort {
+            params.push(format!("sort={}", sort));
+        }
+        if let Some(nearby) = &q.nearby {
+            params.push(format!("nearby={}", nearby));
+        }
+        if !params.is_empty() {
+            path.push('?');
+            path.push_str(&params.join("&"));
+        }
+    }
+
+    api_client.get(Endpoint::Custom(path)).await
+}

src/api/client.rs

@@ -2,9 +2,10 @@ use anyhow::{Result, anyhow};
 use reqwest::Client;
 use serde::de::DeserializeOwned;
 
-const BASE_URL: &str = "https://api.stoat.chat";
+use crate::api::API_BASE_URL;
 
 #[derive(Debug)]
+#[allow(unused)]
 pub enum Endpoint {
     Config,
     CurrentUser,
@@ -14,6 +15,7 @@ pub enum Endpoint {
     Channel(String),
     MessageHistory(String),
     SendMessage(String),
+    Custom(String),
 }
 
 impl Endpoint {
@@ -27,27 +29,31 @@ impl Endpoint {
             Self::Channel(id) => format!("/channels/{}", id),
             Self::MessageHistory(id) => format!("/channels/{}/messages", id),
             Self::SendMessage(id) => format!("/channels/{}/messages", id),
+            Self::Custom(path) => path.clone(),
         }
     }
 }
 
+#[derive(Debug, Clone)]
 pub struct ApiClient {
     client: Client,
     token: String,
+    base_url: String,
 }
 
 impl ApiClient {
-    pub fn new(token: String) -> Self {
+    pub fn new(token: String, base_url: Option<String>) -> Self {
         Self {
             client: Client::new(),
             token,
+            base_url: base_url.unwrap_or(API_BASE_URL.to_string()),
         }
     }
 
     /// Makes a GET request to the specified endpoint and deserializes the JSON response into `T`.
     /// The `endpoint` should start with a slash, e.g., `/users/@me`.
     pub async fn get<T: DeserializeOwned>(&self, endpoint: Endpoint) -> Result<T> {
-        let url = format!("{}{}", BASE_URL, endpoint.path());
+        let url = format!("{}{}", self.base_url, endpoint.path());
 
         let response = self
             .client
@@ -70,6 +76,40 @@ impl ApiClient {
             ))
         }
     }
+
+    pub async fn post<T: DeserializeOwned, B: serde::Serialize>(
+        &self,
+        endpoint: Endpoint,
+        body: &B,
+    ) -> Result<T> {
+        let url = format!("{}{}", self.base_url, endpoint.path());
+
+        let response = self
+            .client
+            .post(&url)
+            .header("X-Session-Token", &self.token)
+            .json(body)
+            .send()
+            .await?;
+
+        if response.status().is_success() {
+            let data = response.json::<T>().await?;
+            Ok(data)
+        } else {
+            let status = response.status();
+            let text = response.text().await.unwrap_or_default();
+            Err(anyhow!(
+                "API POST request to {:?} failed: {} - {}",
+                endpoint,
+                status,
+                text
+            ))
+        }
+    }
+
+    pub fn clone_token(&self) -> String {
+        self.token.clone()
+    }
 }
 
 #[cfg(test)]
@@ -80,7 +120,7 @@ mod tests {
     #[tokio::test]
     async fn test_get_config() {
         // Token doesn't matter for the root config endpoint, but we provide a dummy one
-        let client = ApiClient::new("dummy_token".to_string());
+        let client = ApiClient::new("dummy_token".to_string(), None);
 
         let result = client.get::<Value>(Endpoint::Config).await;
         assert!(result.is_ok(), "Failed to get config: {:?}", result.err());