📸 Qinstagram

Enterprise Private API Architecture & Real-Time Engagement Kit

High-performance Rust toolkit for advanced Instagram Direct messaging, automated feeds, and real-time storytelling

⚠️ 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. You assume all operational liabilities.

---

🚀 Quick Start

cargo add qinstagram

Or add to your Cargo.toml:

[dependencies]
qinstagram = "0.1"
tokio = { version = "1", features = ["full"] }

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

Module	Description	Docs
auth	Stateful Password login, 2FA challenge responses, Session lifecycle & persistent multi-user credentials	📖
transport	Payload signing, deterministic device ID generation, request header synthesis, and Android emulation	📖

💬 Direct Communication

Module	Description	Docs
unified_direct	Direct message fetching, fuzzy inbox search, message parser engine, un-sending	📖
media_upload	Two-step direct media configuration and rupload data injection	📖
broadcast	Liking, reacting, responding with URL parsing and state tracking	📖

🎞️ Experiences

Module	Description	Docs
stories	Story and reels gathering, tray parsing, real-time media seen tracking capabilities	📖
feed	News inbox analysis, timeline extraction and pagination	📖
realtime	MQTT Skywalker integration behind --features realtime	📖

🔌 Ecosystem Integrations

Module	Description	Docs
graphql	100% declarative schema mapping (Qicro Standard) securely mapping query/mutation contexts on auth environments	📖
ws	Native axum drop-in logic exposing underlying MQTT binaries to high-speed JSON web sockets via tokio-broadcaster	📖

📚 Full documentation index: docs/readme.md

---

🚀 Usage

Session Injection & Media Tracking

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:

[dependencies]
qinstagram = { version = "0.1.0", features = ["realtime", "graphql", "websocket"] }

All feature flags

# Subsystem Engines
realtime = []
media = []

# Architectural Frameworks
graphql = ["async-graphql"]
websocket = ["axum", "futures-util"]

# Development Mocks
tests-mock = []

---

🏗️ Build

# 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

Metric	Value
Total modules	9
Extracted Data Types	~60
Real-time MQTT endpoints	2
HTTP Message Builders	14
Supported Media Upload	Photo + Video + Link

---

👤 Author

Keyvan Arasteh @keyvanarasteh

---

_{Built with 🦀 Rust — İstinye University}