nodejs-insta-private-api-mqtt 1.3.30 → 1.3.32

package/README.md

@@ -1,3 +1,294 @@
+# All-in-One Instagram protocol — MQTT + REST API
+
+**This project emulates the Instagram Mobile App behavior _completely_ — both the real-time MQTT layer and the HTTP/REST private API.**
+
+Use **MQTT** for realtime messaging, presence and notifications, and use **REST/private HTTP endpoints** for account management, media upload/configuration, story/reel publishing, and other non-realtime interactions. The examples below show extended REST/API usage patterns and helpers so the library can act like a full mobile client.
+
+---
+
+
+
+# REST API Examples — Expanded (many common mobile-client patterns)
+
+> The examples below use an `ig` client instance (e.g. `const ig = new IgApiClient()`) and show common REST/private-endpoint flows developers rely on to emulate mobile-client behavior. They are written in idiomatic Node.js style.
+
+## Authentication & Session Management (login, 2FA, challenges, session save/restore)
+
+```javascript
+const { IgApiClient, useMultiFileAuthState } = require('nodejs-insta-private-api-mqtt');
+const fs = require('fs');
+
+async function loginFlow() {
+  const ig = new IgApiClient();
+  ig.state.generateDevice?.('username_here');
+
+  // Optional: load saved session state
+  if (fs.existsSync('./state.json')) {
+    const raw = JSON.parse(fs.readFileSync('./state.json', 'utf8'));
+    if (ig.state.deserialize) await ig.state.deserialize(raw);
+  }
+
+  try {
+    await ig.account.login('username_here', 'password_here');
+    // successful login: persist state
+    if (ig.state.serialize) {
+      fs.writeFileSync('./state.json', JSON.stringify(ig.state.serialize()));
+    }
+  } catch (err) {
+    // handle 2FA / challenge-style flows
+    if (err.name === 'IgCheckpointError' || err.message?.includes('challenge')) {
+      // Example: prompt user for challenge code or handle via ig.challenge API
+      console.log('Challenge required — resolve via ig.challenge or user input');
+    } else if (err.name === 'IgLoginTwoFactorRequiredError') {
+      // provide the security code from user
+      const code = await promptUserForCode();
+      await ig.account.twoFactorLogin({ username: 'username_here', verificationCode: code });
+    } else {
+      throw err;
+    }
+  }
+}
+```
+
+## Device & Header Emulation Helpers
+
+```javascript
+// create device + set headers similar to a mobile device
+ig.state.generateDevice('username_here');
+ig.request.setHeaders({
+  'User-Agent': 'Instagram 999.0.0.0 Android (28/9; 420dpi; 1080x1920; brand; model; rom; en_US)',
+  'X-IG-App-ID': '567067343352427',
+});
+```
+
+## User & Profile endpoints (lookup, info, followers/following)
+
+```javascript
+// get a userId and profile
+const userId = await ig.user.getIdByUsername('natgeo');
+const profile = await ig.user.info(userId);
+console.log('username:', profile.username, 'full name:', profile.full_name);
+
+// followers iterator (paginated generator)
+const followersFeed = ig.feed.accountFollowers(userId);
+for await (const page of followersFeed.items()) {
+  for (const follower of page) {
+    console.log(follower.username, follower.pk);
+  }
+  // break if you just wanted first page
+  break;
+}
+```
+
+## Feed / Timeline / Explore
+
+```javascript
+const timeline = await ig.feed.timeline().request();
+console.log('timeline items:', timeline.items.length);
+
+// explore / discover feed
+const explore = await ig.feed.discover().request();
+console.log('explore length:', explore.items?.length || 0);
+```
+
+## Search (users, hashtags, locations)
+
+```javascript
+// user search
+const users = await ig.search.searchUsers('travel');
+console.log('users found:', users.users?.length);
+
+// tag search
+const tag = await ig.feed.tag('sunset', 'top').request();
+console.log('tag items:', tag.items?.length);
+
+// location search
+const locations = await ig.search.location('New York', { rank_token: '1' });
+```
+
+## Media retrieval, comments, likes
+
+```javascript
+// media info
+const mediaId = '1234567890123456789_123456789';
+const mediaInfo = await ig.media.info(mediaId);
+console.log('media taken at:', mediaInfo.taken_at);
+
+// comments
+const comments = await ig.media.comments(mediaId);
+await ig.media.comment({ mediaId, text: 'Great shot!' });
+// delete comment
+await ig.media.deleteComment({ mediaId, commentId: '987654321' });
+
+// likes
+await ig.media.like({ mediaId });
+await ig.media.unlike({ mediaId });
+```
+
+## Upload photo (rupload + configure) — robust with retries and backoff
+
+```javascript
+const fs = require('fs');
+const { v4: uuidv4 } = require('uuid');
+
+async function ruploadWithRetries(ig, path, tries = 3) {
+  const buffer = fs.readFileSync(path);
+  let lastErr;
+  for (let attempt = 1; attempt <= tries; attempt++) {
+    try {
+      const uploadId = Date.now().toString();
+      const objectName = `${uploadId}_${Math.floor(Math.random() * 1e9)}.jpg`;
+      const ruploadParams = {
+        upload_id: uploadId,
+        media_type: 1,
+        image_compression: '{"lib_name":"moz","lib_version":"3.1.m","quality":"80"}'
+      };
+      await ig.request.send({
+        url: `/rupload_igphoto/${objectName}`,
+        method: 'POST',
+        headers: {
+          'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+          'Content-Type': 'image/jpeg',
+          'X-Entity-Type': 'image/jpeg',
+          'X-Entity-Length': String(buffer.length),
+          'Content-Length': String(buffer.length)
+        },
+        body: buffer,
+        timeout: 120000
+      });
+
+      // configure
+      const resp = await ig.request.send({
+        url: '/api/v1/media/configure/?',
+        method: 'POST',
+        form: {
+          upload_id: uploadId,
+          caption: 'Uploaded via script',
+          client_context: uuidv4()
+        },
+        timeout: 60000
+      });
+      return resp;
+    } catch (err) {
+      lastErr = err;
+      const wait = Math.pow(2, attempt) * 1000;
+      await new Promise(res => setTimeout(res, wait));
+    }
+  }
+  throw lastErr;
+}
+```
+
+## Upload video (chunked rupload + configure)
+
+```javascript
+// chunked upload example (simplified): split buffer into parts and send multipart rupload endpoints
+async function uploadVideo(ig, videoPath) {
+  const buffer = fs.readFileSync(videoPath);
+  const uploadId = Date.now().toString();
+  // many clients use segmented uploads for large videos (upload each chunk to /rupload_igvideo/...)
+  // and then call /api/v1/media/configure/?video=1 with video metadata (duration, poster_frame_index, etc.)
+  // Use ig.request.send with appropriate X-Entity headers and X-Instagram-Rupload-Params for each chunk.
+}
+```
+
+## Stories & Reels (upload story, reply to story, story with sticker)
+
+```javascript
+// publish simple story image
+async function publishStory(ig, imageBuffer) {
+  // helper if exists
+  if (ig.publish?.story) return ig.publish.story({ file: imageBuffer });
+
+  // otherwise rupload + configure via /api/v1/media/configure_to_story/
+  // pass story-specific metadata (e.g. story_expires_at, allow_multi_configure)
+}
+
+// reply to a story via direct (HTTP fallback)
+await ig.direct.sendStoryReply({ threadId: '123', text: 'Nice story!' });
+```
+
+## Direct messaging (HTTP fallbacks): send messages, attachments, thread operations
+
+```javascript
+// send a text message via HTTP direct API (fallback if not using MQTT)
+await ig.direct.send({
+  recipients: [threadId],
+  action: 'send_item',
+  client_context: uuidv4(),
+  item: { type: 'text', text: 'Hello via HTTP' }
+});
+
+// send an image as a message (rupload, then attach to direct send)
+async function sendImageAsDirect(ig, imageBuffer, threadId) {
+  // 1) rupload image bytes (rupload_igphoto)
+  // 2) call /api/v1/direct_v2/threads/broadcast/configure_photo/ with upload_id and thread_ids
+}
+```
+
+## Inbox and thread management
+
+```javascript
+// list inbox threads (paginated)
+const threadsFeed = ig.feed.directInbox();
+for await (const page of threadsFeed.items()) {
+  for (const thread of page) {
+    console.log('thread:', thread.thread_id, 'unread:', thread.unread_count);
+  }
+  break;
+}
+
+// mark thread as seen
+await ig.direct.markThreadSeen('1234567890');
+```
+
+## Saved collections, highlights, and story highlights
+
+```javascript
+// save media to collection
+await ig.media.save({ mediaId: '12345' });
+// create collection: endpoints differ; use request.send if no helper exists
+await ig.request.send({ url: '/api/v1/collections/create/', method: 'POST', form: { name: 'My collection' } });
+```
+
+## Business Insights (for business accounts) — example patterns
+
+```javascript
+// fetch account insights (requires business auth/permissions)
+const insights = await ig.account.getInsights({ metric: ['impressions', 'reach'], period: 'week' });
+console.log('insights', insights);
+```
+
+## Rate limiting & retry helper (simple guard)
+
+```javascript
+// simple queue-based rate limit guard
+class RateLimiter {
+  constructor(minDelay = 500) { this.minDelay = minDelay; this.last = 0; }
+  async wait() {
+    const now = Date.now();
+    const diff = this.minDelay - (now - this.last);
+    if (diff > 0) await new Promise(res => setTimeout(res, diff));
+    this.last = Date.now();
+  }
+}
+const rl = new RateLimiter(600);
+await rl.wait();
+await ig.user.info(someId);
+```
+
+## Utilities: generic request wrapper for arbitrary endpoints
+
+```javascript
+const resp = await ig.request.send({
+  url: '/api/v1/users/' + someId + '/info/',
+  method: 'GET'
+});
+console.log('raw response', resp);
+```
+
+---
+
 Dear users,
 I post many versions of the project because Instagram changes the protocol almost daily, if you like this project leave a star on github https://github.com/Kunboruto20/nodejs-insta-private-api.git 
 
@@ -2294,3 +2585,255 @@ async function sendVideoViaRestBroadcast({ ig, videoBuffer, threadId, caption =
 ---
 
 (Section added programmatically: `Examples using ig.request.send` — appended to the existing README content.)
+
+
+
+---
+
+# Additional: Extended HTTP/API Features (inspired by /)
+
+> NOTE: The MQTT sections of this README were left unchanged. The content below **adds** the common HTTP/REST and client helper features typically available in the popular `` () library, and shows idiomatic English code snippets to help users of `nodejs-insta-private-api-mqtt` access the same non-MQTT features. These examples are illustrative — adapt to your codebase and helpers.
+
+## Overview of added features
+
+This project already focuses on MQTT real-time messaging. The following list collects common **HTTP/REST and client helper features** found in `` implementations and shows how to call equivalent functionality using the `IgApiClient` exported by `nodejs-insta-private-api-mqtt`:
+
+- Account & session management (snapshot/restore, generateDevice, session serialization)
+- Authentication helpers (login, two-factor handlers, challenge resolution)
+- User endpoints (get user info, getIdByUsername, followers / following iterators)
+- Feeds and discovery (timeline, explore, reels tray, user feeds, tag feeds, location feeds)
+- Media publishing (upload photo, upload video, configure/broadcast)
+- Stories & reels (upload stories, get story tray, reply to story)
+- Comments & likes (post comment, delete, list comments; like/unlike media)
+- Relationships (follow, unfollow, block, unblock, pending requests)
+- Search (users, tags, locations)
+- Direct (HTTP-based DM methods as an alternative to MQTT where applicable)
+- Helpers: `request` / `ig.request.send` wrapper for arbitrary private endpoints
+- Media helpers: rupload flow helpers, rupload params, and retry/backoff patterns
+- Utilities: rate-limit guard, pagination iterators, and feed cursors
+
+The sections and examples below show typical usage patterns.
+
+---
+
+## Account & Session Helpers
+
+```javascript
+const { IgApiClient, useMultiFileAuthState } = require('nodejs-insta-private-api-mqtt');
+const fs = require('fs');
+
+async function snapshotRestoreExample() {
+  const ig = new IgApiClient();
+
+  // 1) Generate device based on username (if needed)
+  ig.state.generateDevice?.('my_username'); // safe-guard: method may exist on this client
+
+  // 2) Login
+  await ig.login({ username: process.env.IG_USERNAME, password: process.env.IG_PASSWORD });
+
+  // 3) Serialize session snapshot to JSON (save to disk)
+  const snapshot = ig.state.serialize ? ig.state.serialize() : null;
+  if (snapshot) fs.writeFileSync('./ig-state.json', JSON.stringify(snapshot));
+
+  // 4) Later: restore the session snapshot
+  const raw = fs.readFileSync('./ig-state.json', 'utf8');
+  const session = JSON.parse(raw);
+  if (ig.state.deserialize) await ig.state.deserialize(session);
+}
+```
+
+**Two-factor / Challenge note:** When login triggers 2FA or challenge flow, use the library's login exceptions and the `ig.challenge` / `ig.twoFactor` helpers (or prompt the user), then call `authState.saveCreds(ig)` afterwards.
+
+---
+
+## User & Relationship APIs
+
+```javascript
+// get user id by username + follow/unfollow
+const ig = new IgApiClient();
+
+async function userExamples() {
+  const userId = await ig.user.getIdByUsername('example_user');
+  const userInfo = await ig.user.info(userId);
+  console.log('User info:', userInfo.username, userInfo.pk);
+
+  // follow
+  await ig.friendship.create(userId);
+
+  // unfollow
+  await ig.friendship.destroy(userId);
+
+  // get followers (paginated generator style)
+  for await (const page of ig.feed.accountFollowers(userId).items()) {
+    // page is one chunk of followers; in many libs you call .items() or .then(...)
+    console.log('follower page length', page.length);
+    break; // example only
+  }
+}
+```
+
+---
+
+## Feeds, Search & Discover
+
+```javascript
+// timeline, reels, tag search
+const ig = new IgApiClient();
+
+async function feedsAndSearch() {
+  // timeline
+  const timeline = await ig.feed.timeline().request();
+  console.log('Timeline length:', timeline.items?.length);
+
+  // search users
+  const users = await ig.search.users('search query');
+  console.log('Matching users:', users.users?.slice(0,5).map(u => u.username));
+
+  // tag feed
+  const tagFeed = await ig.feed.tag('cats', 'recent').request();
+  console.log('Tag feed items:', tagFeed.items?.length);
+
+  // location feed
+  const locFeed = await ig.feed.location('213999449').request();
+  console.log('Location items:', locFeed.items?.length);
+}
+```
+
+---
+
+## Media Publishing (photo / video) — HTTP rupload + configure flow
+
+> Reminder (already present in README): **always rupload bytes via HTTP** and then attach via HTTP broadcast/configure endpoint. MQTT is only used as a realtime reference.
+
+```javascript
+const fs = require('fs');
+const { v4: uuidv4 } = require('uuid');
+
+async function uploadPhotoExample(ig, filePath, threadIds = []) {
+  const buffer = fs.readFileSync(filePath);
+
+  // Prefer library helper if available
+  if (typeof ig.publish?.photo === 'function') {
+    const res = await ig.publish.photo({ file: buffer, caption: 'Hello from bot' });
+    return res.upload_id || res;
+  }
+
+  // Manual rupload fallback
+  const uploadId = Date.now().toString();
+  const objectName = `${uploadId}_${Math.floor(Math.random() * 1e9)}.jpg`;
+  const ruploadParams = {
+    upload_id: uploadId,
+    media_type: 1,
+    image_compression: '{"lib_name":"moz","lib_version":"3.1.m","quality":"80"}'
+  };
+
+  await ig.request.send({
+    url: `/rupload_igphoto/${objectName}`,
+    method: 'POST',
+    headers: {
+      'X-Instagram-Rupload-Params': JSON.stringify(ruploadParams),
+      'Content-Type': 'image/jpeg',
+      'X-Entity-Type': 'image/jpeg',
+      'X-Entity-Length': String(buffer.length),
+      'Content-Length': String(buffer.length)
+    },
+    body: buffer,
+    timeout: 120000
+  });
+
+  // Then configure/broadcast via HTTP (server-side message creation)
+  const payload = {
+    upload_id: String(uploadId),
+    caption: 'Uploaded from script',
+    thread_ids: JSON.stringify(threadIds),
+    client_context: uuidv4()
+  };
+
+  const resp = await ig.request.send({
+    url: '/api/v1/direct_v2/threads/broadcast/configure_photo/',
+    method: 'POST',
+    form: payload,
+    timeout: 60000
+  });
+
+  return uploadId;
+}
+```
+
+---
+
+## Stories & Reels
+
+```javascript
+// publish story (helper) or rupload+configure
+async function publishStory(ig, imageBuffer) {
+  if (typeof ig.publish?.story === 'function') {
+    return await ig.publish.story({ file: imageBuffer });
+  }
+  // fallback: rupload + configure_story endpoint
+}
+```
+
+---
+
+## Comments & Likes
+
+```javascript
+// comment on a media and then delete comment
+await ig.media.comment({ mediaId: '1234567890', text: 'Nice post!' });
+// delete
+await ig.media.deleteComment({ mediaId: '1234567890', commentId: '111222333' });
+
+// like media
+await ig.media.like({ mediaId: '1234567890' });
+// unlike
+await ig.media.unlike({ mediaId: '1234567890' });
+```
+
+---
+
+## Direct (HTTP fallbacks and helpers)
+
+Although MQTT is the real-time engine in this project, many `` users rely on HTTP direct endpoints for message sending or backup flows:
+
+```javascript
+// Send a DM using HTTP direct endpoint (fallback)
+await ig.direct.send({
+  threadId: threadId,
+  item: { type: 'text', text: 'Hello via HTTP' }
+});
+```
+
+---
+
+## Request helper: call arbitrary private endpoints
+
+```javascript
+// ig.request.send is a flexible wrapper to call private endpoints
+const resp = await ig.request.send({
+  url: '/api/v1/users/' + userId + '/info/',
+  method: 'GET'
+});
+console.log('raw user info:', resp);
+```
+
+---
+
+## Utilities & Best Practices (summarized)
+
+- Implement retries and exponential backoff for rupload and configure calls.
+- Rate-limit heavy operations (bulk follows, mass downloads).
+- Save `upload_id`, `client_context` and server responses for debugging.
+- Use `useMultiFileAuthState()` for persistent multi-file sessions (already present in this repo).
+- For large media uploads, prefer library helpers (`ig.publish.video`, `ig.publish.photo`) that implement chunked/segmented uploads.
+
+---
+
+## Attribution & Sources
+
+- Original README and MQTT content preserved from the uploaded file. Reference to the original uploaded README: 
+- Feature examples and inspiration based on the  `` project documentation. See: https://github.com//. 
+
+---
+
+# End of appended section