diff --git a/README.md b/README.md index 57f074f..a69eae9 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,55 @@ # ๐Ÿ•’ insta-note-clock -> **A high-resilience Rust CLI daemon that synchronizes your Instagram Note with a live digital clock at a safe, configurable interval.** +A lightweight Rust CLI daemon that updates your Instagram Note with the current time at a configurable, safe interval. + +> โš ๏ธ **Disclaimer:** Instagram has no public API for Notes. This tool interacts with private mobile endpoints, which violates Instagram's Terms of Service. Frequent updates risk rate limits (HTTP 429) or account suspension. Default interval is 120s with exponential backoff. Use at your own risk. --- -### โš ๏ธ IMPORTANT LEGAL & TERMS OF SERVICE WARNING - -> [!CAUTION] -> **USE AT YOUR OWN RISK.** -> -> 1. Instagram / Meta has **no public API** for Notes. This tool interacts directly with Instagram's private Android mobile application endpoints. -> 2. Automating actions on Instagram directly violates **Section 3.2 of Instagram's Terms of Use** (*"You can't attempt to create accounts or access or collect information in unauthorized ways"* and *"You must not access Instagram's private API by means other than the Instagram app or website"*). -> 3. Instagram utilizes aggressive automated fraud detection and rate limiting. Frequent Note mutations (e.g., updating every 60 seconds) will almost certainly trigger HTTP 429 errors, action blocks, checkpoint challenges, or **permanent account suspension / ban**. -> 4. This tool enforces a **minimum safe default of 120 seconds**, a **rolling 30 requests/hour cap**, and **exponential backoff + jitter**. **Never use your primary personal account if you cannot afford to lose it.** Test with a secondary or disposable account first. - ---- - -## ๐Ÿ—๏ธ Architecture & Reverse Engineered Endpoints - -Existing open-source Rust crates were evaluated: -- `insta-rs`, `qinstagram`: Outdated and predate Instagram Notes (introduced in 2022/2023). -- `goofy`, `rocketapi`: Unofficial wrapper services or SaaS requiring third-party API keys and recurring subscriptions. - -Consequently, `insta-note-clock` implements a **native Rust HTTP engine using `reqwest`**, reverse-engineered directly from Instagram's Android client and referenced from the Python `instagrapi` library (`instagrapi.mixins.note`). - -### Endpoint Specification - -| Action | HTTP Method & Path | Form Payload | Headers / Cookies | -| :--- | :--- | :--- | :--- | -| **Create/Update Note** | `POST https://i.instagram.com/api/v1/notes/create_note` | `signed_body=SIGNATURE.{"note_style":0,"text":"...","_uuid":"...","audience":0}` | `sessionid`, `ds_user_id`, `csrftoken`, `X-IG-App-ID: 936619743392459`, `User-Agent: Android` | -| **Delete Note** | `POST https://i.instagram.com/api/v1/notes/delete_note/` | `signed_body=SIGNATURE.{"id":"","_uuid":"..."}` | Same as above | -| **Get Notes Tray** | `POST https://i.instagram.com/api/v1/notes/get_notes` | `signed_body=SIGNATURE.{"_uuid":"..."}` | Same as above | -| **Account Login** | `POST https://i.instagram.com/api/v1/accounts/login/` | `signed_body=SIGNATURE.{"username":"...","enc_password":"#PWD_INSTAGRAM:0::",...}` | Mobile device headers | -| **2FA Verification** | `POST https://i.instagram.com/api/v1/accounts/two_factor_login/` | `signed_body=SIGNATURE.{"username":"...","verification_code":"...","two_factor_identifier":"...",...}` | Mobile device headers | - -> **Note on Atomic Replacement:** Instagram enforces a strict limit of **one active Note per account**. Calling `create_note` automatically replaces any prior note on Instagram's server side without needing an explicit deletion step. - ---- - -## ๐Ÿ›ก๏ธ Safety & Rate Limiting Mechanics - -- **Default Interval:** 120 seconds (warns visibly if configured lower). -- **Hourly Budget Cap:** Limits mutations to a rolling maximum of 30 requests/hour by default. -- **HTTP 429 Backoff:** On receiving rate limit code 429, the daemon pauses for an exponential backoff starting at **5 minutes (300 seconds)** + random jitter (5โ€“30s), retrying up to 3 times before halting. -- **Immediate Fatal Exit on 401/403:** The daemon never loops or retries authentication failures, preventing credential lockout. -- **Dry Run Mode:** Test payloads, formatting, and time calculations without making any network requests. - ---- - -## ๐Ÿ“ฆ Project Structure - -``` -insta-note-clock/ -โ”œโ”€โ”€ Cargo.toml # Rust package & dependency definitions -โ”œโ”€โ”€ .env.example # Template for environment variable overrides -โ”œโ”€โ”€ config.example.toml # Example TOML configuration file -โ”œโ”€โ”€ config.toml # Active configuration file -โ”œโ”€โ”€ .gitignore # Prevents secrets or session.json from leaking -โ”œโ”€โ”€ README.md # Comprehensive documentation -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ lib.rs # Library root re-exporting core modules -โ”‚ โ”œโ”€โ”€ main.rs # CLI entrypoint, argument parsing & daemon loop -โ”‚ โ”œโ”€โ”€ client.rs # Instagram private API client, signing & backoff -โ”‚ โ”œโ”€โ”€ clock.rs # Timezone parsing & note formatting logic -โ”‚ โ”œโ”€โ”€ config.rs # Configuration loading & validation logic -โ”‚ โ””โ”€โ”€ session.rs # Session persistence & secure disk storage -โ””โ”€โ”€ tests/ - โ””โ”€โ”€ mock_test.rs # WireMock integration tests (zero live API calls) -``` - ---- - -## ๐Ÿš€ Installation & Building - -### Prerequisites -- Rust stable (1.75+) with `cargo` +## Quick Start +### 1. Build ```bash -git clone insta-note-clock -cd insta-note-clock cargo build --release ``` -The compiled binary will be located at `target/release/insta-note-clock`. + +### 2. Authenticate +```bash +# Option A: Direct session cookie import (recommended) +cargo run -- login --session-id "YOUR_SESSION_ID" --user-id "YOUR_DS_USER_ID" + +# Option B: Interactive login (supports 2FA) +cargo run -- login +``` +Session data will be stored securely in `session.json`. + +### 3. Run +```bash +# Test run without hitting Instagram +cargo run -- --dry-run once + +# Update once and exit +cargo run -- once + +# Run continuous sync loop +cargo run -- run +``` --- -## โš™๏ธ Configuration - -You can configure `insta-note-clock` via `config.toml` or environment variables (prefixed with `INSTA_`). - -### `config.toml` +## Configuration (`config.toml`) ```toml [instagram] -username = "your_username" -password = "" # Optional: leave blank for interactive login or session cookies session_file = "./session.json" -timezone = "Asia/Kolkata" # Any valid IANA timezone (e.g., "America/New_York", "UTC") +timezone = "Asia/Kolkata" [note] -interval_seconds = 120 # Minimum recommended: 120 seconds -time_format = "%H:%M" # strftime format (%H:%M for 24h, %I:%M %p for 12h) -prefix = "๐Ÿ•’ " # Prefix placed before time -suffix = "" # Optional suffix (Note limit: 60 chars) -max_requests_per_hour = 30 # Rolling hourly safety cap +interval_seconds = 120 # Minimum recommended: 120s +time_format = "%H:%M" # strftime syntax +prefix = "๐Ÿ•’ " +suffix = "" +max_requests_per_hour = 30 ``` ---- - -## ๐Ÿ”‘ Authentication Guide - -`insta-note-clock` supports two methods: - -### Method 1: Direct Session Cookie Import (Recommended โญ) -*This is the safest method because it bypasses Instagram's mobile automated login bot detection.* - -1. Log in to [instagram.com](https://instagram.com) in Chrome, Firefox, or Edge. -2. Press `F12` to open Developer Tools, go to **Application** (or **Storage**) -> **Cookies** -> `https://www.instagram.com`. -3. Locate the `sessionid` and `ds_user_id` cookies. -4. Run: - ```bash - insta-note-clock login --session-id "YOUR_SESSION_ID" --user-id "YOUR_DS_USER_ID" - ``` - Or launch `insta-note-clock login` and select Option `2`. - -### Method 2: Interactive Login (with 2FA) -Run: -```bash -insta-note-clock login -``` -Select option `1`. You will be prompted for your username, password (hidden input), and 2FA SMS / Authenticator verification code if enabled. - -Once authenticated, your session is securely saved to `session.json` with `0600` permissions and reused on subsequent runs. - ---- - -## ๐Ÿ’ป CLI Usage - -### 1. Test in Dry-Run Mode (Safe) -Simulate formatting and verify the request payload without hitting Instagram: -```bash -cargo run -- --dry-run once -``` - -### 2. Update Note Once -Post a single timestamp Note update and exit: -```bash -cargo run -- once -``` - -### 3. Run Daemon Loop -Start the clock synchronization daemon: -```bash -cargo run -- run -``` -To exit cleanly, press `Ctrl+C`. - ---- - -## ๐Ÿ“ฑ Running on Android Tablet Server (Termux) - -If deploying to your Android tablet server running Termux: - -1. Install prerequisites in Termux: - ```bash - pkg update - pkg install rust binutils openssl - ``` -2. Copy or clone the project into Termux: - ```bash - cd ~/insta-note-clock - cargo build --release - ``` -3. Authenticate: - ```bash - ./target/release/insta-note-clock login - ``` -4. Run under `tmux` or `nohup`: - ```bash - tmux new -s note-clock - ./target/release/insta-note-clock run - # Detach with Ctrl+B then D - ``` - ---- - -## ๐Ÿงช Testing - -Run unit tests and mocked integration tests: -```bash -cargo test -``` -All integration tests utilize `wiremock` to simulate Instagram's API responses locally without ever sending external network packets. +Environment variables with prefix `INSTA_` (e.g. `INSTA_NOTE__INTERVAL_SECONDS=120`) are also supported.