<p align="center">
<h1 align="center">πΈ Qinstagram</h1>
<p align="center">
<strong>Enterprise Private API Architecture & Real-Time Engagement Kit</strong>
</p>
<p align="center">
High-performance Rust toolkit for advanced Instagram Direct messaging, automated feeds, and real-time storytelling
</p>
</p>
<p align="center">
<a href="https://crates.io/crates/qinstagram"><img src="https://img.shields.io/crates/v/qinstagram?style=for-the-badge&logo=rust&logoColor=white&color=orange" alt="crates.io"></a>
<a href="https://docs.rs/qinstagram"><img src="https://img.shields.io/docsrs/qinstagram?style=for-the-badge&logo=docs.rs&logoColor=white" alt="docs.rs"></a>
<a href="https://github.com/keyvanarasteh/Qinstagram/actions"><img src="https://img.shields.io/github/actions/workflow/status/keyvanarasteh/Qinstagram/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI"></a>
<a href="https://github.com/keyvanarasteh/Qinstagram/blob/main/LICENSE"><img src="https://img.shields.io/crates/l/qinstagram?style=for-the-badge" alt="License"></a>
</p>
<p align="center">
<a href="#"><img src="https://img.shields.io/badge/async-tokio-purple?style=flat-square&logo=tokio" alt="Tokio"></a>
<a href="#"><img src="https://img.shields.io/badge/http-reqwest-blue?style=flat-square" alt="Reqwest"></a>
<a href="#"><img src="https://img.shields.io/badge/GraphQL-async_graphql-e535ab?style=flat-square&logo=graphql" alt="GraphQL"></a>
<a href="#"><img src="https://img.shields.io/badge/WebSocket-tokio_broadcast-blue?style=flat-square" alt="WebSocket"></a>
<a href="#"><img src="https://img.shields.io/badge/mqtt-rumqttc-red?style=flat-square" alt="MQTT"></a>
<a href="#"><img src="https://img.shields.io/badge/platform-linux-lightgrey?style=flat-square&logo=linux" alt="Linux"></a>
</p>
> β οΈ **Compliance Warning**: This toolkit interfaces directly with Meta's Private API surface. It is engineered strictly for educational research, security emulation, and authorized AI infrastructure design. Violation of the primary Instagram Terms Of Service (e.g. unsolicited spam, fake account orchestration) via this library may result in severe account penalties or legal [Cease & Desist orders](https://www.facebook.com/help/instagram/). You assume all operational liabilities.
---
## π Quick Start
```bash
cargo add qinstagram
```
Or add to your `Cargo.toml`:
```toml
[dependencies]
qinstagram = "0.1"
tokio = { version = "1", features = ["full"] }
```
```rust
use qinstagram::client::InstagramClient;
use qinstagram::config::LoginConfig;
#[tokio::main]
async fn main() {
let mut client = InstagramClient::builder()
.credentials("username", "password")
.build()
.unwrap();
// Authenticate and establish secure session (supports 2FA & Checkpoints)
client.login().await.unwrap();
// Directly access messaging infrastructure
let threads = client.get_threads(None).await.unwrap();
println!("Fetched {} direct threads", threads.threads.len());
}
```
> **Selective features**: `cargo add qinstagram --no-default-features --features realtime,media`
---
## β¨ Features
- **4 distinct workflow modules** cleanly organized reflecting Instagram's domain architecture.
- **Enterprise GraphQL Parity** β Drops cleanly into external architectural ecosystems like Qicro matching 100% of endpoints via Schema definition logic.
- **WebSocket Push Capabilities** β Bridge MQTT direct into React/Svelte5 frontends via Tokio sync broadcasts.
- **Panic-free Library** β robust error handling wrapping and propagating `InstagramError` instances.
- **Two-Factor and Challenge Flows** β seamlessly navigate verification checkpoint gates.
- **MQTT Event Capabilities** β unified fallback messaging and real-time syncing.
- **Ruploado Media Configuration** β highly complex custom media routing built manually into Rust.
---
## π¦ Module Overview
### π Authentication & Session
| **auth** | Stateful Password login, 2FA challenge responses, Session lifecycle & persistent multi-user credentials | [π](docs/auth.md) |
| **transport** | Payload signing, deterministic device ID generation, request header synthesis, and Android emulation | [π](docs/auth.md) |
### π¬ Direct Communication
| **unified_direct** | Direct message fetching, fuzzy inbox search, message parser engine, un-sending | [π](docs/direct.md) |
| **media_upload** | Two-step direct media configuration and rupload data injection | [π](docs/direct.md) |
| **broadcast** | Liking, reacting, responding with URL parsing and state tracking | [π](docs/direct.md) |
### ποΈ Experiences
| **stories** | Story and reels gathering, tray parsing, real-time media seen tracking capabilities | [π](docs/stories.md) |
| **feed** | News inbox analysis, timeline extraction and pagination | [π](docs/feed.md) |
| **realtime** | MQTT Skywalker integration behind `--features realtime` | [π](docs/realtime.md) |
### π Ecosystem Integrations
| **graphql** | 100% declarative schema mapping (Qicro Standard) securely mapping query/mutation contexts on auth environments | [π](docs/graphql.md) |
| **ws** | Native `axum` drop-in logic exposing underlying MQTT binaries to high-speed JSON web sockets via tokio-broadcaster | [π](docs/websocket.md) |
> π **Full documentation index:** [docs/readme.md](docs/readme.md)
---
## π Usage
### Session Injection & Media Tracking
```rust
use qinstagram::client::InstagramClient;
#[tokio::main]
async fn main() {
let client = InstagramClient::from_session("username").await.unwrap();
// Exfiltrate media targeting
let media_candidates = client.get_reels_tray().await.unwrap();
// Broadcast Seen State back to network
client.mark_stories_as_seen(&media_candidates[0].stories).await.unwrap();
// Send Reactions
let target_thread = client.search_thread_by_username("friend_account").await.unwrap();
client.send_reaction(&target_thread.unwrap().thread_id, "12345_67", "π₯").await.unwrap();
}
```
---
## βοΈ Feature Flags
Include only what you need:
```toml
[dependencies]
qinstagram = { version = "0.1.0", features = ["realtime", "graphql", "websocket"] }
```
<details>
<summary><strong>All feature flags</strong></summary>
```toml
# Subsystem Engines
realtime = []
media = []
# Architectural Frameworks
graphql = ["async-graphql"]
websocket = ["axum", "futures-util"]
# Development Mocks
tests-mock = []
```
</details>
---
## ποΈ Build
```bash
# Core framework
cargo build
# All experimental modules
cargo build --all-features
# Release compilation
cargo build --all-features --release
# Run rigorous unit tests and offline mock parsers
cargo test --all-features
```
---
## π Project Structure
```
Qinstagram/
βββ Cargo.toml # Dependencies & architectural flags
βββ README.md # This file
βββ src/
β βββ lib.rs # API facade and Module exports
β β
β βββ auth/ # Sessions, Challenges & Verification
β βββ direct/ # Thread logic, Search, Broadcast, Parser
β βββ feed/ # Core API Timelines
β βββ media/ # Downloads & Complex Upload Protocols
β βββ realtime/ # Under heavy development MQTT
β βββ stories/ # Trays & state persistence
β βββ transport/ # Emulation context and networking
β βββ types/ # Struct parity wrappers
β
βββ docs/ # Component Reference Documentation
β βββ readme.md # Documentation index
β βββ [module_name].md
β
βββ examples/ # Real-world usage scenarios
βββ tests/ # Offline JSON structural integrity testing
```
---
## π Stats
| Total modules | 9 |
| Extracted Data Types | ~60 |
| Real-time MQTT endpoints| 2 |
| HTTP Message Builders | 14 |
| Supported Media Upload | Photo + Video + Link |
---
## π€ Author
<table>
<tr>
<td align="center">
<a href="https://github.com/keyvanarasteh">
<img src="https://github.com/keyvanarasteh.png" width="80" height="80" style="border-radius:50%" alt="Keyvan Arasteh"><br>
<sub><b>Keyvan Arasteh</b></sub><br>
<sub>@keyvanarasteh</sub>
</a>
</td>
</tr>
</table>
---
<p align="center">
<sub>Built with π¦ Rust β Δ°stinye University</sub>
</p>