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

package/README.md

@@ -1,294 +1,3 @@
-# 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 
 
@@ -2585,255 +2294,3 @@ 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