@vicociv/instaloader 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,386 @@
+# @vicociv/instaloader
+
+TypeScript port of [instaloader](https://github.com/instaloader/instaloader) - Download Instagram content (posts, stories, profiles) with metadata.
+
+## Installation
+
+```bash
+npm install @vicociv/instaloader
+```
+
+**Requirements:** Node.js >= 18.0.0
+
+## Quick Start
+
+```typescript
+import { Instaloader, Profile, Post, Hashtag } from '@vicociv/instaloader';
+
+const L = new Instaloader();
+
+// Get a post by shortcode (works without login)
+const post = await L.getPost('DSsaqgbkhAd');
+console.log(post.caption);
+console.log(post.typename);  // 'GraphImage' | 'GraphVideo' | 'GraphSidecar'
+
+// Get a profile
+const profile = await L.getProfile('instagram');
+console.log(await profile.getFollowers()); // follower count
+
+// Iterate posts
+for await (const post of profile.getPosts()) {
+  console.log(post.shortcode, post.likes);
+}
+```
+
+## Authentication
+
+Most operations work without login. However, login is required for:
+- Accessing private profiles
+- Viewing stories and highlights
+- Saved posts
+- Some rate-limited operations
+
+```typescript
+// Login with credentials
+await L.login('username', 'password');
+
+// Handle 2FA if required
+try {
+  await L.login('username', 'password');
+} catch (e) {
+  if (e instanceof TwoFactorAuthRequiredException) {
+    await L.twoFactorLogin('123456');
+  }
+}
+
+// Save/load session
+await L.saveSessionToFile('session.json');
+await L.loadSessionFromFile('username', 'session.json');
+
+// Test if session is valid
+const username = await L.testLogin(); // returns username or null
+```
+
+## API Reference
+
+### Instaloader
+
+Main class for downloading Instagram content.
+
+```typescript
+const L = new Instaloader(options?: InstaloaderOptions);
+```
+
+**Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sleep` | boolean | true | Enable rate limiting delays |
+| `quiet` | boolean | false | Suppress console output |
+| `userAgent` | string | - | Custom user agent |
+| `downloadPictures` | boolean | true | Download images |
+| `downloadVideos` | boolean | true | Download videos |
+| `saveMetadata` | boolean | true | Save JSON metadata |
+
+#### Get Content
+
+```typescript
+// Get profile/post/hashtag
+const profile = await L.getProfile('username');
+const post = await L.getPost('shortcode');
+const hashtag = await L.getHashtag('nature');
+```
+
+#### Download Content
+
+```typescript
+// Download a single post
+await L.downloadPost(post, 'target_folder');
+
+// Download profile posts
+await L.downloadProfile(profile, {
+  maxCount: 10,
+  fastUpdate: true, // stop at already downloaded
+  postFilter: (p) => p.likes > 100,
+});
+
+// Download hashtag posts
+await L.downloadHashtag(hashtag, { maxCount: 50 });
+```
+
+### Profile
+
+Represents an Instagram user profile.
+
+```typescript
+import { Profile } from '@vicociv/instaloader';
+
+// Create from username
+const profile = await Profile.fromUsername(context, 'instagram');
+
+// Properties (sync)
+profile.username      // lowercase username
+profile.userid        // numeric user ID
+profile.is_private    // is private account
+profile.followed_by_viewer
+profile.follows_viewer
+
+// Properties (async - may fetch metadata)
+await profile.getFollowers()
+await profile.getFollowees()
+await profile.getMediacount()
+await profile.getBiography()
+await profile.getFullName()
+await profile.getProfilePicUrl()
+await profile.getIsVerified()
+await profile.getExternalUrl()
+```
+
+#### Iterate Posts
+
+```typescript
+// All posts
+for await (const post of profile.getPosts()) {
+  console.log(post.shortcode);
+}
+
+// Saved posts (requires login as owner)
+for await (const post of profile.getSavedPosts()) {
+  console.log(post.shortcode);
+}
+
+// Tagged posts
+for await (const post of profile.getTaggedPosts()) {
+  console.log(post.shortcode);
+}
+```
+
+### Post
+
+Represents an Instagram post.
+
+```typescript
+import { Post } from '@vicociv/instaloader';
+
+// Create from shortcode
+const post = await Post.fromShortcode(context, 'ABC123');
+
+// Properties
+post.shortcode        // URL shortcode
+post.mediaid          // BigInt media ID
+post.typename         // 'GraphImage' | 'GraphVideo' | 'GraphSidecar'
+post.url              // image/thumbnail URL
+post.video_url        // video URL (if video)
+post.is_video         // boolean
+post.caption          // caption text
+post.caption_hashtags // ['tag1', 'tag2']
+post.caption_mentions // ['user1', 'user2']
+post.likes            // like count
+post.comments         // comment count
+post.date_utc         // Date object
+post.tagged_users     // tagged usernames
+
+// Get owner profile
+const owner = await post.getOwnerProfile();
+
+// Sidecar (carousel) posts
+for (const node of post.getSidecarNodes()) {
+  console.log(node.is_video, node.display_url, node.video_url);
+}
+```
+
+### Hashtag
+
+Represents an Instagram hashtag.
+
+```typescript
+import { Hashtag } from '@vicociv/instaloader';
+
+const hashtag = await Hashtag.fromName(context, 'photography');
+
+// Properties
+hashtag.name                    // lowercase name (without #)
+await hashtag.getHashtagId()
+await hashtag.getMediacount()
+await hashtag.getProfilePicUrl()
+
+// Get posts (use getPostsResumable for reliable pagination)
+const iterator = hashtag.getPostsResumable();
+for await (const post of iterator) {
+  console.log(post.shortcode);
+}
+
+// Top posts
+for await (const post of hashtag.getTopPosts()) {
+  console.log(post.shortcode);
+}
+```
+
+### Story & StoryItem
+
+```typescript
+import { Story, StoryItem } from '@vicociv/instaloader';
+
+// Story contains multiple StoryItems
+for await (const item of story.getItems()) {
+  console.log(item.mediaid);
+  console.log(item.typename);     // 'GraphStoryImage' | 'GraphStoryVideo'
+  console.log(item.url);          // image URL
+  console.log(item.video_url);    // video URL (if video)
+  console.log(item.date_utc);
+  console.log(item.expiring_utc);
+}
+```
+
+### Highlight
+
+Extends Story for profile highlights.
+
+```typescript
+import { Highlight } from '@vicociv/instaloader';
+
+highlight.title       // highlight title
+highlight.cover_url   // cover image URL
+
+for await (const item of highlight.getItems()) {
+  // ...
+}
+```
+
+### TopSearchResults
+
+Search Instagram for profiles, hashtags, and locations.
+
+```typescript
+import { TopSearchResults } from '@vicociv/instaloader';
+
+const search = new TopSearchResults(context, 'query');
+
+for await (const profile of search.getProfiles()) {
+  console.log(profile.username);
+}
+
+for await (const hashtag of search.getHashtags()) {
+  console.log(hashtag.name);
+}
+
+for await (const location of search.getLocations()) {
+  console.log(location.name, location.lat, location.lng);
+}
+```
+
+### NodeIterator
+
+Paginated iterator with resume support.
+
+```typescript
+import { NodeIterator, FrozenNodeIterator } from '@vicociv/instaloader';
+
+const iterator = profile.getPosts();
+
+// Iterate
+for await (const post of iterator) {
+  // Save state for resume
+  const state = iterator.freeze();
+  fs.writeFileSync('state.json', JSON.stringify(state));
+  break;
+}
+
+// Resume later
+const savedState = JSON.parse(fs.readFileSync('state.json', 'utf-8'));
+const frozen = new FrozenNodeIterator(savedState);
+const resumed = frozen.thaw(context);
+```
+
+### Helper Functions
+
+```typescript
+import {
+  shortcodeToMediaid,
+  mediaidToShortcode,
+  extractHashtags,
+  extractMentions,
+  parseInstagramUrl,
+  extractShortcode,
+  extractUsername,
+  extractHashtagFromUrl,
+  getJsonStructure,
+  loadStructure,
+} from '@vicociv/instaloader';
+
+// Convert between shortcode and mediaid
+const mediaid = shortcodeToMediaid('ABC123');     // BigInt
+const shortcode = mediaidToShortcode(mediaid);    // string
+
+// Extract from text
+extractHashtags('Hello #world #test');  // ['world', 'test']
+extractMentions('Hello @user1 @user2'); // ['user1', 'user2']
+
+// Parse Instagram URLs
+parseInstagramUrl('https://www.instagram.com/p/DSsaqgbkhAd/')
+// => { type: 'post', shortcode: 'DSsaqgbkhAd' }
+
+parseInstagramUrl('https://www.instagram.com/instagram/')
+// => { type: 'profile', username: 'instagram' }
+
+parseInstagramUrl('https://www.instagram.com/explore/tags/nature/')
+// => { type: 'hashtag', hashtag: 'nature' }
+
+// Extract specific identifiers from URLs
+extractShortcode('https://www.instagram.com/p/DSsaqgbkhAd/?img_index=1')
+// => 'DSsaqgbkhAd'
+
+extractUsername('https://www.instagram.com/instagram/')
+// => 'instagram'
+
+extractHashtagFromUrl('https://www.instagram.com/explore/tags/nature/')
+// => 'nature'
+
+// JSON serialization
+const json = getJsonStructure(post);
+const restored = loadStructure(context, json);
+```
+
+### InstaloaderContext
+
+Low-level API for direct Instagram requests. Usually accessed via `Instaloader.context`.
+
+```typescript
+const context = L.context;
+
+// Check login status
+context.is_logged_in  // boolean
+context.username      // string | null
+
+// Make GraphQL queries
+const data = await context.graphql_query(queryHash, variables);
+const data = await context.doc_id_graphql_query(docId, variables);
+
+// Generic JSON request
+const data = await context.getJson('path', params);
+
+// iPhone API
+const data = await context.get_iphone_json('api/v1/...', params);
+```
+
+### Exceptions
+
+```typescript
+import {
+  InstaloaderException,        // Base exception
+  LoginException,              // Login failed
+  LoginRequiredException,      // Action requires login
+  TwoFactorAuthRequiredException,
+  BadCredentialsException,     // Wrong password
+  ConnectionException,         // Network error
+  TooManyRequestsException,    // Rate limited (429)
+  ProfileNotExistsException,   // Profile not found
+  QueryReturnedNotFoundException,
+  QueryReturnedForbiddenException,
+  PostChangedException,        // Post changed during download
+  InvalidArgumentException,
+} from '@vicociv/instaloader';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -474,6 +474,8 @@ interface FrozenIteratorState {
 declare function defaultUserAgent(): string;
 /**
  * Returns default iPhone headers for API requests.
+ * Note: x-pigeon-session-id and x-ig-connection-speed are randomized per call
+ * to make each request appear as a different client (important for bypassing rate limits).
  */
 declare function defaultIphoneHeaders(): HttpHeaders;
 /**
@@ -627,6 +629,8 @@ declare class InstaloaderContext {
         usePost?: boolean;
         attempt?: number;
         headers?: HttpHeaders;
+        /** If true, refresh dynamic headers (timestamp, session ID, speed) on each attempt */
+        refreshDynamicHeaders?: boolean;
     }): Promise<JsonObject>;
     /**
      * Do a GraphQL Query.
@@ -634,10 +638,13 @@ declare class InstaloaderContext {
     graphql_query(queryHash: string, variables: JsonObject, referer?: string): Promise<JsonObject>;
     /**
      * Do a doc_id-based GraphQL Query using POST.
+     * Each request uses fresh dynamic headers (timestamp, connection speed, session ID)
+     * to appear as different clients, which helps bypass rate limiting on retries.
      */
     doc_id_graphql_query(docId: string, variables: JsonObject, referer?: string): Promise<JsonObject>;
     /**
      * JSON request to i.instagram.com.
+     * Each request uses fresh dynamic headers to appear as different clients.
      */
     get_iphone_json(path: string, params: JsonObject): Promise<JsonObject>;
     /**
@@ -964,6 +971,65 @@ declare function extractHashtags(text: string): string[];
  * Extract @mentions from text.
  */
 declare function extractMentions(text: string): string[];
+/**
+ * Result of parsing an Instagram URL
+ */
+interface ParsedInstagramUrl {
+    type: 'post' | 'profile' | 'hashtag' | 'unknown';
+    shortcode?: string;
+    username?: string;
+    hashtag?: string;
+}
+/**
+ * Parse an Instagram URL to extract the type and identifier.
+ *
+ * @param url - The Instagram URL to parse
+ * @returns Parsed URL information
+ *
+ * @example
+ * parseInstagramUrl('https://www.instagram.com/p/DSsaqgbkhAd/')
+ * // => { type: 'post', shortcode: 'DSsaqgbkhAd' }
+ *
+ * parseInstagramUrl('https://www.instagram.com/instagram/')
+ * // => { type: 'profile', username: 'instagram' }
+ *
+ * parseInstagramUrl('https://www.instagram.com/explore/tags/nature/')
+ * // => { type: 'hashtag', hashtag: 'nature' }
+ */
+declare function parseInstagramUrl(url: string): ParsedInstagramUrl;
+/**
+ * Extract shortcode from a post URL.
+ *
+ * @param url - The Instagram post URL
+ * @returns The shortcode, or null if not found
+ *
+ * @example
+ * extractShortcode('https://www.instagram.com/p/DSsaqgbkhAd/?img_index=1')
+ * // => 'DSsaqgbkhAd'
+ */
+declare function extractShortcode(url: string): string | null;
+/**
+ * Extract username from a profile URL.
+ *
+ * @param url - The Instagram profile URL
+ * @returns The username, or null if not found
+ *
+ * @example
+ * extractUsername('https://www.instagram.com/instagram/')
+ * // => 'instagram'
+ */
+declare function extractUsername(url: string): string | null;
+/**
+ * Extract hashtag from a hashtag URL.
+ *
+ * @param url - The Instagram hashtag URL
+ * @returns The hashtag (without #), or null if not found
+ *
+ * @example
+ * extractHashtagFromUrl('https://www.instagram.com/explore/tags/nature/')
+ * // => 'nature'
+ */
+declare function extractHashtagFromUrl(url: string): string | null;
 /**
  * Represents a comment on a post.
  */
@@ -1661,4 +1727,4 @@ declare class Instaloader {
     getHashtag(name: string): Promise<Hashtag>;
 }
 
-export { AbortDownloadException, BadCredentialsException, BadResponseException, CheckpointRequiredException, type CommentNode, ConnectionException, type CookieData, type EdgeConnection, type FrozenIteratorState, FrozenNodeIterator, type GraphQLResponse, Hashtag, type HashtagNode, Highlight, type HighlightNode, type HttpHeaders, type IPhoneHeaders, IPhoneSupportDisabledException, Instaloader, InstaloaderContext, type InstaloaderContextOptions, InstaloaderException, type InstaloaderOptions, InvalidArgumentException, InvalidIteratorException, type JsonExportable, type JsonObject, type JsonValue, type LocationNode, LoginException, LoginRequiredException, type LoginResponse, NodeIterator, type NodeIteratorOptions, type PageInfo, type PhoneVerificationSettings, Post, PostChangedException, PostComment, type PostCommentAnswer, type PostLocation, type PostNode, type PostSidecarNode, PrivateProfileNotFollowedException, Profile, ProfileHasNoPicsException, type ProfileNode, ProfileNotExistsException, QueryReturnedBadRequestException, QueryReturnedForbiddenException, QueryReturnedNotFoundException, type QueryTimestamps, RateController, type RequestOptions, type ResponseInfo, type ResumableIterationOptions, type ResumableIterationResult, type SessionData, SessionNotFoundException, Story, StoryItem, type StoryItemNode, NodeIterator as StructureNodeIterator, TooManyRequestsException, TopSearchResults, TwoFactorAuthRequiredException, type TwoFactorInfo, defaultIphoneHeaders, defaultUserAgent, extractHashtags, extractMentions, formatFilename, formatStringContainsKey, getConfigDir, getDefaultSessionFilename, getDefaultStampsFilename, getJsonStructure, loadStructure, mediaidToShortcode, resumableIteration, sanitizePath, shortcodeToMediaid };
+export { AbortDownloadException, BadCredentialsException, BadResponseException, CheckpointRequiredException, type CommentNode, ConnectionException, type CookieData, type EdgeConnection, type FrozenIteratorState, FrozenNodeIterator, type GraphQLResponse, Hashtag, type HashtagNode, Highlight, type HighlightNode, type HttpHeaders, type IPhoneHeaders, IPhoneSupportDisabledException, Instaloader, InstaloaderContext, type InstaloaderContextOptions, InstaloaderException, type InstaloaderOptions, InvalidArgumentException, InvalidIteratorException, type JsonExportable, type JsonObject, type JsonValue, type LocationNode, LoginException, LoginRequiredException, type LoginResponse, NodeIterator, type NodeIteratorOptions, type PageInfo, type ParsedInstagramUrl, type PhoneVerificationSettings, Post, PostChangedException, PostComment, type PostCommentAnswer, type PostLocation, type PostNode, type PostSidecarNode, PrivateProfileNotFollowedException, Profile, ProfileHasNoPicsException, type ProfileNode, ProfileNotExistsException, QueryReturnedBadRequestException, QueryReturnedForbiddenException, QueryReturnedNotFoundException, type QueryTimestamps, RateController, type RequestOptions, type ResponseInfo, type ResumableIterationOptions, type ResumableIterationResult, type SessionData, SessionNotFoundException, Story, StoryItem, type StoryItemNode, NodeIterator as StructureNodeIterator, TooManyRequestsException, TopSearchResults, TwoFactorAuthRequiredException, type TwoFactorInfo, defaultIphoneHeaders, defaultUserAgent, extractHashtagFromUrl, extractHashtags, extractMentions, extractShortcode, extractUsername, formatFilename, formatStringContainsKey, getConfigDir, getDefaultSessionFilename, getDefaultStampsFilename, getJsonStructure, loadStructure, mediaidToShortcode, parseInstagramUrl, resumableIteration, sanitizePath, shortcodeToMediaid };

package/dist/index.d.ts

@@ -474,6 +474,8 @@ interface FrozenIteratorState {
 declare function defaultUserAgent(): string;
 /**
  * Returns default iPhone headers for API requests.
+ * Note: x-pigeon-session-id and x-ig-connection-speed are randomized per call
+ * to make each request appear as a different client (important for bypassing rate limits).
  */
 declare function defaultIphoneHeaders(): HttpHeaders;
 /**
@@ -627,6 +629,8 @@ declare class InstaloaderContext {
         usePost?: boolean;
         attempt?: number;
         headers?: HttpHeaders;
+        /** If true, refresh dynamic headers (timestamp, session ID, speed) on each attempt */
+        refreshDynamicHeaders?: boolean;
     }): Promise<JsonObject>;
     /**
      * Do a GraphQL Query.
@@ -634,10 +638,13 @@ declare class InstaloaderContext {
     graphql_query(queryHash: string, variables: JsonObject, referer?: string): Promise<JsonObject>;
     /**
      * Do a doc_id-based GraphQL Query using POST.
+     * Each request uses fresh dynamic headers (timestamp, connection speed, session ID)
+     * to appear as different clients, which helps bypass rate limiting on retries.
      */
     doc_id_graphql_query(docId: string, variables: JsonObject, referer?: string): Promise<JsonObject>;
     /**
      * JSON request to i.instagram.com.
+     * Each request uses fresh dynamic headers to appear as different clients.
      */
     get_iphone_json(path: string, params: JsonObject): Promise<JsonObject>;
     /**
@@ -964,6 +971,65 @@ declare function extractHashtags(text: string): string[];
  * Extract @mentions from text.
  */
 declare function extractMentions(text: string): string[];
+/**
+ * Result of parsing an Instagram URL
+ */
+interface ParsedInstagramUrl {
+    type: 'post' | 'profile' | 'hashtag' | 'unknown';
+    shortcode?: string;
+    username?: string;
+    hashtag?: string;
+}
+/**
+ * Parse an Instagram URL to extract the type and identifier.
+ *
+ * @param url - The Instagram URL to parse
+ * @returns Parsed URL information
+ *
+ * @example
+ * parseInstagramUrl('https://www.instagram.com/p/DSsaqgbkhAd/')
+ * // => { type: 'post', shortcode: 'DSsaqgbkhAd' }
+ *
+ * parseInstagramUrl('https://www.instagram.com/instagram/')
+ * // => { type: 'profile', username: 'instagram' }
+ *
+ * parseInstagramUrl('https://www.instagram.com/explore/tags/nature/')
+ * // => { type: 'hashtag', hashtag: 'nature' }
+ */
+declare function parseInstagramUrl(url: string): ParsedInstagramUrl;
+/**
+ * Extract shortcode from a post URL.
+ *
+ * @param url - The Instagram post URL
+ * @returns The shortcode, or null if not found
+ *
+ * @example
+ * extractShortcode('https://www.instagram.com/p/DSsaqgbkhAd/?img_index=1')
+ * // => 'DSsaqgbkhAd'
+ */
+declare function extractShortcode(url: string): string | null;
+/**
+ * Extract username from a profile URL.
+ *
+ * @param url - The Instagram profile URL
+ * @returns The username, or null if not found
+ *
+ * @example
+ * extractUsername('https://www.instagram.com/instagram/')
+ * // => 'instagram'
+ */
+declare function extractUsername(url: string): string | null;
+/**
+ * Extract hashtag from a hashtag URL.
+ *
+ * @param url - The Instagram hashtag URL
+ * @returns The hashtag (without #), or null if not found
+ *
+ * @example
+ * extractHashtagFromUrl('https://www.instagram.com/explore/tags/nature/')
+ * // => 'nature'
+ */
+declare function extractHashtagFromUrl(url: string): string | null;
 /**
  * Represents a comment on a post.
  */
@@ -1661,4 +1727,4 @@ declare class Instaloader {
     getHashtag(name: string): Promise<Hashtag>;
 }
 
-export { AbortDownloadException, BadCredentialsException, BadResponseException, CheckpointRequiredException, type CommentNode, ConnectionException, type CookieData, type EdgeConnection, type FrozenIteratorState, FrozenNodeIterator, type GraphQLResponse, Hashtag, type HashtagNode, Highlight, type HighlightNode, type HttpHeaders, type IPhoneHeaders, IPhoneSupportDisabledException, Instaloader, InstaloaderContext, type InstaloaderContextOptions, InstaloaderException, type InstaloaderOptions, InvalidArgumentException, InvalidIteratorException, type JsonExportable, type JsonObject, type JsonValue, type LocationNode, LoginException, LoginRequiredException, type LoginResponse, NodeIterator, type NodeIteratorOptions, type PageInfo, type PhoneVerificationSettings, Post, PostChangedException, PostComment, type PostCommentAnswer, type PostLocation, type PostNode, type PostSidecarNode, PrivateProfileNotFollowedException, Profile, ProfileHasNoPicsException, type ProfileNode, ProfileNotExistsException, QueryReturnedBadRequestException, QueryReturnedForbiddenException, QueryReturnedNotFoundException, type QueryTimestamps, RateController, type RequestOptions, type ResponseInfo, type ResumableIterationOptions, type ResumableIterationResult, type SessionData, SessionNotFoundException, Story, StoryItem, type StoryItemNode, NodeIterator as StructureNodeIterator, TooManyRequestsException, TopSearchResults, TwoFactorAuthRequiredException, type TwoFactorInfo, defaultIphoneHeaders, defaultUserAgent, extractHashtags, extractMentions, formatFilename, formatStringContainsKey, getConfigDir, getDefaultSessionFilename, getDefaultStampsFilename, getJsonStructure, loadStructure, mediaidToShortcode, resumableIteration, sanitizePath, shortcodeToMediaid };
+export { AbortDownloadException, BadCredentialsException, BadResponseException, CheckpointRequiredException, type CommentNode, ConnectionException, type CookieData, type EdgeConnection, type FrozenIteratorState, FrozenNodeIterator, type GraphQLResponse, Hashtag, type HashtagNode, Highlight, type HighlightNode, type HttpHeaders, type IPhoneHeaders, IPhoneSupportDisabledException, Instaloader, InstaloaderContext, type InstaloaderContextOptions, InstaloaderException, type InstaloaderOptions, InvalidArgumentException, InvalidIteratorException, type JsonExportable, type JsonObject, type JsonValue, type LocationNode, LoginException, LoginRequiredException, type LoginResponse, NodeIterator, type NodeIteratorOptions, type PageInfo, type ParsedInstagramUrl, type PhoneVerificationSettings, Post, PostChangedException, PostComment, type PostCommentAnswer, type PostLocation, type PostNode, type PostSidecarNode, PrivateProfileNotFollowedException, Profile, ProfileHasNoPicsException, type ProfileNode, ProfileNotExistsException, QueryReturnedBadRequestException, QueryReturnedForbiddenException, QueryReturnedNotFoundException, type QueryTimestamps, RateController, type RequestOptions, type ResponseInfo, type ResumableIterationOptions, type ResumableIterationResult, type SessionData, SessionNotFoundException, Story, StoryItem, type StoryItemNode, NodeIterator as StructureNodeIterator, TooManyRequestsException, TopSearchResults, TwoFactorAuthRequiredException, type TwoFactorInfo, defaultIphoneHeaders, defaultUserAgent, extractHashtagFromUrl, extractHashtags, extractMentions, extractShortcode, extractUsername, formatFilename, formatStringContainsKey, getConfigDir, getDefaultSessionFilename, getDefaultStampsFilename, getJsonStructure, loadStructure, mediaidToShortcode, parseInstagramUrl, resumableIteration, sanitizePath, shortcodeToMediaid };

package/dist/index.js

@@ -66,8 +66,11 @@ __export(index_exports, {
   TwoFactorAuthRequiredException: () => TwoFactorAuthRequiredException,
   defaultIphoneHeaders: () => defaultIphoneHeaders,
   defaultUserAgent: () => defaultUserAgent,
+  extractHashtagFromUrl: () => extractHashtagFromUrl,
   extractHashtags: () => extractHashtags,
   extractMentions: () => extractMentions,
+  extractShortcode: () => extractShortcode,
+  extractUsername: () => extractUsername,
   formatFilename: () => formatFilename,
   formatStringContainsKey: () => formatStringContainsKey,
   getConfigDir: () => getConfigDir,
@@ -76,6 +79,7 @@ __export(index_exports, {
   getJsonStructure: () => getJsonStructure,
   loadStructure: () => loadStructure,
   mediaidToShortcode: () => mediaidToShortcode,
+  parseInstagramUrl: () => parseInstagramUrl,
   resumableIteration: () => resumableIteration,
   sanitizePath: () => sanitizePath,
   shortcodeToMediaid: () => shortcodeToMediaid
@@ -251,6 +255,13 @@ function defaultIphoneHeaders() {
     "x-whatsapp": "0"
   };
 }
+function getPerRequestHeaders() {
+  return {
+    "x-pigeon-rawclienttime": (Date.now() / 1e3).toFixed(6),
+    "x-ig-connection-speed": `${Math.floor(Math.random() * 19e3) + 1e3}kbps`,
+    "x-pigeon-session-id": (0, import_uuid.v4)()
+  };
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -657,7 +668,8 @@ var InstaloaderContext = class {
       host = "www.instagram.com",
       usePost = false,
       attempt = 1,
-      headers: extraHeaders
+      headers: extraHeaders,
+      refreshDynamicHeaders = false
     } = options;
     const isGraphqlQuery = "query_hash" in params && path2.includes("graphql/query");
     const isDocIdQuery = "doc_id" in params && path2.includes("graphql/query");
@@ -678,10 +690,17 @@ var InstaloaderContext = class {
         await this._rateController.waitBeforeQuery("other");
       }
       const url = new URL(`https://${host}/${path2}`);
+      let headersToUse = extraHeaders;
+      if (refreshDynamicHeaders && extraHeaders) {
+        headersToUse = {
+          ...extraHeaders,
+          ...getPerRequestHeaders()
+        };
+      }
       const headers = {
         ...this._defaultHttpHeader(true),
         Cookie: this._getCookieHeader(url.toString()),
-        ...extraHeaders
+        ...headersToUse
       };
       if (this._csrfToken) {
         headers["X-CSRFToken"] = this._csrfToken;
@@ -803,8 +822,10 @@ HTTP redirect from ${url} to ${redirectUrl}`);
       }
       return this.getJson(path2, params, {
         host,
-        usePost,
+        // usePost is intentionally omitted to default to GET on retry
         attempt: attempt + 1,
+        refreshDynamicHeaders: true,
+        // Refresh headers on retry to appear as different client
         ...extraHeaders !== void 0 && { headers: extraHeaders }
       });
     }
@@ -837,10 +858,14 @@ HTTP redirect from ${url} to ${redirectUrl}`);
   }
   /**
    * Do a doc_id-based GraphQL Query using POST.
+   * Each request uses fresh dynamic headers (timestamp, connection speed, session ID)
+   * to appear as different clients, which helps bypass rate limiting on retries.
    */
   async doc_id_graphql_query(docId, variables, referer) {
+    const perRequestHeaders = getPerRequestHeaders();
     const headers = {
       ...this._defaultHttpHeader(true),
+      ...perRequestHeaders,
       authority: "www.instagram.com",
       scheme: "https",
       accept: "*/*"
@@ -863,12 +888,14 @@ HTTP redirect from ${url} to ${redirectUrl}`);
   }
   /**
    * JSON request to i.instagram.com.
+   * Each request uses fresh dynamic headers to appear as different clients.
    */
   async get_iphone_json(path2, params) {
+    const perRequestHeaders = getPerRequestHeaders();
     const headers = {
       ...this._iphoneHeaders,
-      "ig-intended-user-id": this._userId || "",
-      "x-pigeon-rawclienttime": (Date.now() / 1e3).toFixed(6)
+      ...perRequestHeaders,
+      "ig-intended-user-id": this._userId || ""
     };
     const cookies = this.getCookies("https://i.instagram.com/");
     const headerCookiesMapping = {
@@ -1449,6 +1476,47 @@ function extractMentions(text) {
   }
   return matches;
 }
+var POST_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/(?:p|reel|tv)\/([A-Za-z0-9_-]+)/;
+var PROFILE_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/([A-Za-z0-9._]+)\/?(?:\?.*)?$/;
+var HASHTAG_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/explore\/tags\/([^/?]+)/;
+function parseInstagramUrl(url) {
+  const postMatch = url.match(POST_URL_REGEX);
+  if (postMatch && postMatch[1]) {
+    return { type: "post", shortcode: postMatch[1] };
+  }
+  const hashtagMatch = url.match(HASHTAG_URL_REGEX);
+  if (hashtagMatch && hashtagMatch[1]) {
+    return { type: "hashtag", hashtag: hashtagMatch[1] };
+  }
+  const profileMatch = url.match(PROFILE_URL_REGEX);
+  if (profileMatch && profileMatch[1]) {
+    const nonProfilePaths = [
+      "explore",
+      "accounts",
+      "directory",
+      "about",
+      "legal",
+      "developer",
+      "stories"
+    ];
+    if (!nonProfilePaths.includes(profileMatch[1].toLowerCase())) {
+      return { type: "profile", username: profileMatch[1] };
+    }
+  }
+  return { type: "unknown" };
+}
+function extractShortcode(url) {
+  const match = url.match(POST_URL_REGEX);
+  return match ? match[1] : null;
+}
+function extractUsername(url) {
+  const parsed = parseInstagramUrl(url);
+  return parsed.type === "profile" ? parsed.username ?? null : null;
+}
+function extractHashtagFromUrl(url) {
+  const match = url.match(HASHTAG_URL_REGEX);
+  return match ? match[1] : null;
+}
 function ellipsifyCaption(caption) {
   const pcaption = caption.split("\n").filter((s) => s).map((s) => s.replace(/\//g, "\u2215")).join(" ").trim();
   return pcaption.length > 31 ? pcaption.slice(0, 30) + "\u2026" : pcaption;
@@ -3710,8 +3778,11 @@ var Instaloader = class {
   TwoFactorAuthRequiredException,
   defaultIphoneHeaders,
   defaultUserAgent,
+  extractHashtagFromUrl,
   extractHashtags,
   extractMentions,
+  extractShortcode,
+  extractUsername,
   formatFilename,
   formatStringContainsKey,
   getConfigDir,
@@ -3720,6 +3791,7 @@ var Instaloader = class {
   getJsonStructure,
   loadStructure,
   mediaidToShortcode,
+  parseInstagramUrl,
   resumableIteration,
   sanitizePath,
   shortcodeToMediaid

package/dist/index.mjs

@@ -167,6 +167,13 @@ function defaultIphoneHeaders() {
     "x-whatsapp": "0"
   };
 }
+function getPerRequestHeaders() {
+  return {
+    "x-pigeon-rawclienttime": (Date.now() / 1e3).toFixed(6),
+    "x-ig-connection-speed": `${Math.floor(Math.random() * 19e3) + 1e3}kbps`,
+    "x-pigeon-session-id": uuidv4()
+  };
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -573,7 +580,8 @@ var InstaloaderContext = class {
       host = "www.instagram.com",
       usePost = false,
       attempt = 1,
-      headers: extraHeaders
+      headers: extraHeaders,
+      refreshDynamicHeaders = false
     } = options;
     const isGraphqlQuery = "query_hash" in params && path2.includes("graphql/query");
     const isDocIdQuery = "doc_id" in params && path2.includes("graphql/query");
@@ -594,10 +602,17 @@ var InstaloaderContext = class {
         await this._rateController.waitBeforeQuery("other");
       }
       const url = new URL(`https://${host}/${path2}`);
+      let headersToUse = extraHeaders;
+      if (refreshDynamicHeaders && extraHeaders) {
+        headersToUse = {
+          ...extraHeaders,
+          ...getPerRequestHeaders()
+        };
+      }
       const headers = {
         ...this._defaultHttpHeader(true),
         Cookie: this._getCookieHeader(url.toString()),
-        ...extraHeaders
+        ...headersToUse
       };
       if (this._csrfToken) {
         headers["X-CSRFToken"] = this._csrfToken;
@@ -719,8 +734,10 @@ HTTP redirect from ${url} to ${redirectUrl}`);
       }
       return this.getJson(path2, params, {
         host,
-        usePost,
+        // usePost is intentionally omitted to default to GET on retry
         attempt: attempt + 1,
+        refreshDynamicHeaders: true,
+        // Refresh headers on retry to appear as different client
         ...extraHeaders !== void 0 && { headers: extraHeaders }
       });
     }
@@ -753,10 +770,14 @@ HTTP redirect from ${url} to ${redirectUrl}`);
   }
   /**
    * Do a doc_id-based GraphQL Query using POST.
+   * Each request uses fresh dynamic headers (timestamp, connection speed, session ID)
+   * to appear as different clients, which helps bypass rate limiting on retries.
    */
   async doc_id_graphql_query(docId, variables, referer) {
+    const perRequestHeaders = getPerRequestHeaders();
     const headers = {
       ...this._defaultHttpHeader(true),
+      ...perRequestHeaders,
       authority: "www.instagram.com",
       scheme: "https",
       accept: "*/*"
@@ -779,12 +800,14 @@ HTTP redirect from ${url} to ${redirectUrl}`);
   }
   /**
    * JSON request to i.instagram.com.
+   * Each request uses fresh dynamic headers to appear as different clients.
    */
   async get_iphone_json(path2, params) {
+    const perRequestHeaders = getPerRequestHeaders();
     const headers = {
       ...this._iphoneHeaders,
-      "ig-intended-user-id": this._userId || "",
-      "x-pigeon-rawclienttime": (Date.now() / 1e3).toFixed(6)
+      ...perRequestHeaders,
+      "ig-intended-user-id": this._userId || ""
     };
     const cookies = this.getCookies("https://i.instagram.com/");
     const headerCookiesMapping = {
@@ -1365,6 +1388,47 @@ function extractMentions(text) {
   }
   return matches;
 }
+var POST_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/(?:p|reel|tv)\/([A-Za-z0-9_-]+)/;
+var PROFILE_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/([A-Za-z0-9._]+)\/?(?:\?.*)?$/;
+var HASHTAG_URL_REGEX = /(?:https?:\/\/)?(?:www\.)?instagram\.com\/explore\/tags\/([^/?]+)/;
+function parseInstagramUrl(url) {
+  const postMatch = url.match(POST_URL_REGEX);
+  if (postMatch && postMatch[1]) {
+    return { type: "post", shortcode: postMatch[1] };
+  }
+  const hashtagMatch = url.match(HASHTAG_URL_REGEX);
+  if (hashtagMatch && hashtagMatch[1]) {
+    return { type: "hashtag", hashtag: hashtagMatch[1] };
+  }
+  const profileMatch = url.match(PROFILE_URL_REGEX);
+  if (profileMatch && profileMatch[1]) {
+    const nonProfilePaths = [
+      "explore",
+      "accounts",
+      "directory",
+      "about",
+      "legal",
+      "developer",
+      "stories"
+    ];
+    if (!nonProfilePaths.includes(profileMatch[1].toLowerCase())) {
+      return { type: "profile", username: profileMatch[1] };
+    }
+  }
+  return { type: "unknown" };
+}
+function extractShortcode(url) {
+  const match = url.match(POST_URL_REGEX);
+  return match ? match[1] : null;
+}
+function extractUsername(url) {
+  const parsed = parseInstagramUrl(url);
+  return parsed.type === "profile" ? parsed.username ?? null : null;
+}
+function extractHashtagFromUrl(url) {
+  const match = url.match(HASHTAG_URL_REGEX);
+  return match ? match[1] : null;
+}
 function ellipsifyCaption(caption) {
   const pcaption = caption.split("\n").filter((s) => s).map((s) => s.replace(/\//g, "\u2215")).join(" ").trim();
   return pcaption.length > 31 ? pcaption.slice(0, 30) + "\u2026" : pcaption;
@@ -3625,8 +3689,11 @@ export {
   TwoFactorAuthRequiredException,
   defaultIphoneHeaders,
   defaultUserAgent,
+  extractHashtagFromUrl,
   extractHashtags,
   extractMentions,
+  extractShortcode,
+  extractUsername,
   formatFilename,
   formatStringContainsKey,
   getConfigDir,
@@ -3635,6 +3702,7 @@ export {
   getJsonStructure,
   loadStructure,
   mediaidToShortcode,
+  parseInstagramUrl,
   resumableIteration,
   sanitizePath,
   shortcodeToMediaid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vicociv/instaloader",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript port of instaloader - Download pictures (or videos) along with their captions and other metadata from Instagram.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",