🕒 insta-note-clock

A high-resilience Rust CLI daemon that synchronizes your Instagram Note with a live digital clock at a safe, configurable interval.

---

⚠️ 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":"<note_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:<ts>:<pwd>",...}	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

git clone <repo-url> insta-note-clock
cd insta-note-clock
cargo build --release

The compiled binary will be located at target/release/insta-note-clock.

---

⚙️ Configuration

You can configure insta-note-clock via config.toml or environment variables (prefixed with INSTA_).

config.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")

[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

---

🔑 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 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:

   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:

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:

cargo run -- --dry-run once

2. Update Note Once

Post a single timestamp Note update and exit:

cargo run -- once

3. Run Daemon Loop

Start the clock synchronization daemon:

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:

   pkg update
   pkg install rust binutils openssl
   

2. Copy or clone the project into Termux:

   cd ~/insta-note-clock
   cargo build --release
   

3. Authenticate:

   ./target/release/insta-note-clock login
   

4. Run under tmux or nohup:

   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:

cargo test

All integration tests utilize wiremock to simulate Instagram's API responses locally without ever sending external network packets.