instasave-sdk 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,271 @@
+# Changelog
+
+All notable changes to InstaSave SDK will be documented in this file.
+
+## [1.1.2] - 2026-01-03
+
+### 📦 Package Enhancement
+
+### Added
+- **Complete documentation in npm package** - README_API.md and CHANGELOG.md now included
+- **Offline documentation access** - All docs available in node_modules/instasave-sdk/
+- **Better developer experience** - No need to visit GitHub for API reference
+
+### Changed
+- Updated package.json files array to include documentation files
+- Enhanced npm package contents for better usability
+
+---
+
+## [1.1.1] - 2026-01-03
+
+### 📚 Documentation Update
+
+### Added
+- **Comprehensive README** - Complete rewrite with better structure and examples
+- **Detailed API Reference** - Updated README_API.md with current interfaces
+- **Usage examples** - Step-by-step guides for common scenarios
+- **Error handling guide** - How to handle authentication and timeout errors
+
+### Changed
+- **Better organization** - Clear sections with emojis and formatting
+- **Updated examples** - All code examples use current v1.1.x API
+- **Simplified explanations** - Easier to understand for new users
+
+### Documentation
+- Complete README restructure with Quick Start section
+- Updated all code examples to match simplified metadata
+- Added troubleshooting section with common issues
+- Comprehensive API reference with TypeScript interfaces
+
+---
+
+## [1.1.0] - 2026-01-03
+
+### 🎯 Major Refactor - Simplified & Optimized
+
+### Changed
+- **Simplified metadata interface** - Removed `audio`, `hashtags`, `mentions` fields
+- **Cleaner API** - Only essential metadata: `likesCount`, `commentsCount`, `caption`, `timestamp`, `location`
+- **Improved performance** - Removed complex audio extraction logic
+- **Smaller bundle size** - Eliminated 668+ lines of unused code
+
+### Removed
+- ❌ Audio metadata extraction (not reliably available via web scraping)
+- ❌ Hashtags/mentions extraction from captions
+- ❌ Unused files: `benchmark.ts`, `parallel.ts`, `memory.ts`, `test-integration.ts`, `worker.js`
+- ❌ Deprecated `images` field from MediaData interface
+
+### Fixed
+- **Metadata extraction** - More reliable likes/comments detection with multiple fallbacks
+- **Bundle optimization** - Removed dead code and unused imports
+- **Type safety** - Cleaner TypeScript interfaces
+
+### Technical
+- Updated PostMetadata interface to focus on core data
+- Removed complex DOM parsing for audio/hashtags
+- Simplified extractMetadata function
+- Better error handling for metadata extraction
+
+---
+
+## [1.0.9] - 2026-01-03
+
+### Added
+- **URL normalization** - Consistent Instagram post URL formatting
+- **Cache-busting** - Forces fresh content from Instagram servers
+- **Instagram cache debug** - Cache version tracking in Debug mode
+
+### Features
+- URL Normalizer supports multiple Instagram URL formats
+- Cache-busting headers and browser cache clearing
+- Debug logging for cache keys, file IDs, and versions
+- Eliminates Instagram cache inconsistencies
+
+### Technical
+- Normalizes URLs to `instagram.com/p/ID/` format
+- Timestamp-based cache-busting parameters
+- Chrome DevTools Protocol cache clearing
+- Debug info only in Debug console mode
+
+## [1.0.8] - 2026-01-03
+
+### Added
+- **Smart Logging System** - Two console modes: Classic and Debug
+- **CONSOLE_MODE configuration** - Control logging verbosity via config file
+- **Minimalist output** - Clean, readable logs in Classic mode
+- **Detailed debugging** - Comprehensive logs in Debug mode
+
+### Console Modes
+**Classic Mode (default):**
+```
+📄 Config loaded
+🔐 Session: username
+📸 Scraping: post_id
+✅ Success: 6 images
+```
+
+**Debug Mode:**
+```
+📄 Config loaded from: /path/to/config
+🔐 Session loaded: username
+🔍 Platform: instagram
+🔄 Workflow steps...
+✅ Scraped post_id: 6 images
+```
+
+### Configuration
+```ini
+[SETTINGS]
+CONSOLE_MODE = Classic  # or Debug
+```
+
+### Features
+- **Crawlee log suppression** - Hides verbose crawler statistics in Classic mode
+- **Smart message routing** - Different detail levels per mode
+- **Always show errors** - Critical messages appear in both modes
+- **Backward compatible** - Existing logging still works
+
+## [1.0.7] - 2026-01-03
+
+### Added
+- **AUTO_LOGIN configuration** - Control auto-login behavior in config file
+- **Enhanced login control** - Option to disable auto-login even with credentials
+
+### Configuration Enhancement
+```ini
+[ACCOUNT]
+# Auto login to Instagram (if enable, on start server auto login to instagram)
+AUTO_LOGIN = true
+USERNAME = your_username
+PASSWORD = your_password
+```
+
+### Behavior
+- `AUTO_LOGIN = true` - Automatic login on startup (default)
+- `AUTO_LOGIN = false` - Disable auto-login even with credentials
+- Better logging and debugging for login process
+
+## [1.0.6] - 2026-01-03
+
+### Added
+- **Profile URL extraction** - Now extracts profile URL from Instagram posts
+- **Configuration system** - Support for `instasave.config` file in project root
+- **Auto-login** - Automatic authentication using config file credentials
+- **Enhanced MediaData** - Added `profile_url` field to all scraped data
+
+### New Features
+- **Config file support** - INI format configuration with sections: `[DEFAULT]`, `[ACCOUNT]`, `[SETTINGS]`
+- **Project-specific settings** - Different configurations per project
+- **Environment fallback** - Falls back to environment variables if config not found
+- **Config API** - New methods: `getConfig()`, `getConfigParser()`
+
+### Configuration Example
+```ini
+[DEFAULT]
+PUPPETEER_EXECUTABLE_PATH = /path/to/chrome
+
+[ACCOUNT]
+USERNAME = your_username
+PASSWORD = your_password
+
+[SETTINGS]
+OUTPUT_DIR = ./downloads
+```
+
+### Enhanced Data Structure
+- Added `profile_url` to `MediaData` interface
+- Example: `https://www.instagram.com/username/` extracted from posts
+- Backward compatible with existing code
+
+## [1.0.5] - 2026-01-03
+
+### Fixed
+- **Critical**: Fixed "text is not iterable" error in authentication system
+- **NodeList iteration**: Added `Array.from()` wrapper for `querySelectorAll` results
+- **Login reliability**: Improved authentication success detection
+- **Browser compatibility**: Better support for different browser environments
+
+### Technical Details
+- Fixed 5 instances of NodeList iteration in `auth-fast.ts`
+- All `for...of` loops with `querySelectorAll` now use `Array.from()`
+- Resolves authentication status showing false despite successful login
+
+## [1.0.4] - 2026-01-03
+
+### Removed
+- **BREAKING**: Removed deprecated `scrapePost()` method
+- Use `scrape()` method instead for all operations
+
+### Changed
+- **Clean API** - Single `scrape()` method for all platforms
+- **Modern approach** - `MediaData` format for all responses
+- Updated all examples and documentation to use `scrape()`
+
+### Migration Guide
+```javascript
+// Before (removed)
+const data = await scraper.scrapePost(url);
+console.log(data.images);
+
+// After (use this)
+const data = await scraper.scrape(url);
+console.log(data.media.map(item => item.url));
+```
+
+## [1.0.3] - 2026-01-03
+
+### Added
+- **Progress tracking** - Real-time download progress callbacks
+- **Custom filename patterns** - Template system with `{username}_{postid}_{index}.jpg`
+- **Duplicate detection** - MD5 hash-based file duplicate checking
+- **Session validation** - Automatic login session verification
+- **Enhanced file management** - Advanced file operations with custom naming
+
+### Fixed
+- **Sandbox bypass** - Added `--no-sandbox` arguments for containerized environments
+- **Browser launch options** - Improved compatibility across different systems
+
+### Enhanced
+- **ScrapingOptions** - New options: `progressCallback`, `filenamePattern`, `skipDuplicates`
+- **Error handling** - Better error messages and recovery mechanisms
+- **Performance monitoring** - Enhanced metrics collection
+
+## [1.0.2] - 2026-01-03
+
+### Changed
+- Removed deprecated `InstaScraper` class - use `MediaScraper` only
+- Updated all internal code to use `MediaScraper`
+
+### Fixed
+- Fixed URL pattern matching for Instagram URLs with username prefix
+- Now supports both formats: `instagram.com/p/ABC123/` and `instagram.com/username/p/ABC123/`
+
+### Removed
+- `InstaScraper` class (breaking change - use `MediaScraper` instead)
+
+## [1.0.1] - 2026-01-03
+
+### Changed
+- Optimized dependencies - removed Playwright to reduce package size
+- Updated README with comprehensive examples and troubleshooting
+- Focused on Instagram image scraping only (no videos/reels)
+
+### Fixed
+- Improved error handling for login-required content
+- Better workflow automation for modal handling
+
+### Added
+- Complete test suite with real Instagram URL validation
+- Enhanced documentation with practical examples
+
+## [1.0.0] - 2026-01-03
+
+### Added
+- Initial release of InstaSave SDK
+- Instagram post scraping with authentication support
+- Multi-platform plugin architecture
+- Workflow automation system
+- Metrics and monitoring capabilities
+- Support for single posts and carousel posts
+- Automatic session management

package/README.md

@@ -1,13 +1,104 @@
 # InstaSave SDK
 
-[![Version](https://img.shields.io/badge/version-1.0.9-blue.svg)](https://github.com/nykadamec/instasave-sdk/releases/tag/v1.0.9)
+[![Version](https://img.shields.io/badge/version-1.1.2-blue.svg)](https://github.com/nykadamec/instasave-sdk/releases/tag/v1.1.2)
 [![Changelog](https://img.shields.io/badge/changelog-latest-green.svg)](https://github.com/nykadamec/instasave-sdk/blob/main/CHANGELOG.md)
 
-📸 Simple Instagram scraper for downloading images from posts
+📸 **Simple Instagram scraper for downloading images from posts**
 
-## Configuration
+Fast, reliable, and easy-to-use Instagram media downloader with authentication support.
 
-InstaSave SDK supports configuration via `instasave.config` file in your project root:
+---
+
+## 🚀 Quick Start
+
+```bash
+npm install instasave-sdk
+```
+
+```javascript
+import { MediaScraper } from 'instasave-sdk';
+
+const scraper = new MediaScraper();
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/');
+
+console.log(`Downloaded ${data.media.length} images from @${data.profile_name}`);
+```
+
+---
+
+## 📖 Usage Guide
+
+### Basic Scraping
+
+```javascript
+import { MediaScraper } from 'instasave-sdk';
+
+const scraper = new MediaScraper();
+
+// Download images from Instagram post
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/');
+
+console.log(data);
+// Result:
+// {
+//   url: 'https://www.instagram.com/p/ABC123/',
+//   post_id: 'ABC123',
+//   platform: 'instagram',
+//   profile_name: 'username',
+//   profile_url: 'https://www.instagram.com/username/',
+//   media: [
+//     { url: 'https://instagram.com/image1.jpg', index: 0 },
+//     { url: 'https://instagram.com/image2.jpg', index: 1 }
+//   ],
+//   metadata: {
+//     likesCount: 1234,
+//     commentsCount: 56,
+//     caption: 'Post caption...',
+//     timestamp: null,
+//     location: null
+//   }
+// }
+```
+
+### Save to File
+
+```javascript
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/', {
+  saveToFile: true,           // Save data to JSON file
+  outputPath: './downloads'   // Folder to save to
+});
+```
+
+### Private Posts (Login Required)
+
+```javascript
+// Login first
+await scraper.login({
+  username: 'your_username',
+  password: 'your_password'
+});
+
+// Then download private posts
+const data = await scraper.scrape('https://www.instagram.com/p/private_post/');
+```
+
+### Advanced Options
+
+```javascript
+const data = await scraper.scrape('URL', {
+  saveToFile: true,        // Save to file? (default: false)
+  outputPath: './folder',  // Where to save? (default: current folder)
+  timeout: 60,            // Timeout in seconds (default: 60)
+  retries: 2,             // How many retries on error (default: 0)
+  headless: true          // Hidden browser? (default: true)
+});
+```
+
+---
+
+## ⚙️ Configuration
+
+Create `instasave.config` in your project root for automatic setup:
 
 ```ini
 [DEFAULT]
@@ -29,24 +120,64 @@ TIMEOUT = 60
 - ✅ **Project-specific** - Different settings per project
 - ✅ **Environment fallback** - Falls back to environment variables
 
-## What does it do?
+---
 
-InstaSave SDK allows you to download images from Instagram posts with just a few lines of code. Works with both public and private posts (after login).
+## ✨ Features
 
-## Installation
+### What's Supported
+✅ **Single posts** - One image  
+✅ **Carousel posts** - Multiple images in one post  
+✅ **Private posts** - After login  
+✅ **Auto save** - To JSON file  
+✅ **Error handling** - When something fails  
+✅ **Metadata extraction** - Likes, comments, captions
 
-```bash
-npm install instasave-sdk
-```
+### Limitations
+❌ **Videos/Reels** - Images only  
+❌ **Stories** - Posts only  
+
+---
 
-## Basic Usage
+## 🔧 Troubleshooting
 
-### 1. Download public post
+### Common Issues
 
+**"Login required"**
 ```javascript
-import { MediaScraper } from 'instasave-sdk';
+// Solution: Login before downloading
+await scraper.login({ username: 'user', password: 'pass' });
+```
 
-const scraper = new MediaScraper();
+**"Failed to extract post ID"**
+```javascript
+// Solution: Check URL - must contain /p/
+// ✅ Correct: https://www.instagram.com/p/ABC123/
+// ❌ Wrong: https://www.instagram.com/username/
+```
+
+**"Timeout"**
+```javascript
+// Solution: Increase timeout
+const data = await scraper.scrape(url, { timeout: 120 });
+```
+
+---
+
+## 📋 Requirements
+
+- Node.js 16 or newer
+- Internet connection
+- For private posts: valid Instagram account
+
+---
+
+## 📄 License
+
+MIT - use anywhere
+
+## 🆘 Support
+
+Having issues? Create an [issue on GitHub](https://github.com/nykadamec/instasave-sdk/issues)
 
 // Download images from Instagram post
 const data = await scraper.scrape('https://www.instagram.com/p/ABC123/');

package/README_API.md

@@ -0,0 +1,241 @@
+# InstaSave SDK - API Reference
+
+## Quick Start
+
+```typescript
+import { MediaScraper } from 'instasave-sdk';
+
+const scraper = new MediaScraper();
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/');
+```
+
+## Core API
+
+### `MediaScraper`
+
+Main class for Instagram scraping operations.
+
+#### `scrape(url, options?)`
+
+Scrapes Instagram post and returns media data with metadata.
+
+**Parameters:**
+- `url: string` - Instagram post URL (must contain `/p/`)
+- `options?: ScrapingOptions` - Optional configuration
+
+**Returns:** `Promise<MediaData>`
+
+**Example:**
+```typescript
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/', {
+  saveToFile: true,
+  outputPath: './downloads',
+  headless: true,
+  timeout: 120,
+  retries: 2
+});
+```
+
+#### `login(credentials)`
+
+Authenticate with Instagram for private posts.
+
+**Parameters:**
+- `credentials: LoginCredentials` - Username and password
+
+**Example:**
+```typescript
+await scraper.login({
+  username: 'your_username',
+  password: 'your_password'
+});
+```
+
+## Data Types
+
+### `MediaData`
+```typescript
+interface MediaData {
+  url: string;                    // Original Instagram URL
+  post_id: string;               // Post ID (e.g., "ABC123")
+  platform: string;             // Always "instagram"
+  profile_name: string;          // Profile name
+  profile_url: string;           // Profile URL
+  media: CarouselItem[];         // Array of media items
+  metadata: PostMetadata;        // Post metadata
+}
+```
+
+### `CarouselItem`
+```typescript
+interface CarouselItem {
+  url: string;      // Direct image URL
+  index: number;    // Position in carousel (0-based)
+}
+```
+
+### `PostMetadata`
+```typescript
+interface PostMetadata {
+  likesCount: number | null;     // Number of likes
+  commentsCount: number | null;  // Number of comments
+  caption: string | null;        // Post caption/description
+  timestamp: string | null;      // Post creation time (relative format)
+  location: string | null;       // Location name if available
+}
+```
+
+### `ScrapingOptions`
+```typescript
+interface ScrapingOptions {
+  saveToFile?: boolean;          // Save to JSON file (default: false)
+  outputPath?: string;           // Output directory (default: current dir)
+  timeout?: number;              // Timeout in seconds (default: 60)
+  retries?: number;              // Retry attempts (default: 0)
+  headless?: boolean;            // Run browser in headless mode (default: true)
+}
+```
+
+### `LoginCredentials`
+```typescript
+interface LoginCredentials {
+  username: string;              // Instagram username
+  password: string;              // Instagram password
+}
+```
+
+## Configuration
+
+### Config File (`instasave.config`)
+
+```ini
+[DEFAULT]
+PUPPETEER_EXECUTABLE_PATH = /path/to/chrome
+
+[ACCOUNT]
+USERNAME = your_username
+PASSWORD = your_password
+
+[SETTINGS]
+OUTPUT_DIR = ./downloads
+HEADLESS = true
+TIMEOUT = 60
+CONSOLE_MODE = Classic
+```
+
+## Error Handling
+
+```typescript
+try {
+  const data = await scraper.scrape(url);
+  console.log(`Success: ${data.media.length} images`);
+} catch (error) {
+  if (error.message.includes('Login required')) {
+    await scraper.login({ username: 'user', password: 'pass' });
+    const data = await scraper.scrape(url);
+  } else {
+    console.error('Scraping failed:', error.message);
+  }
+}
+```
+
+## Examples
+
+### Basic Usage
+```typescript
+import { MediaScraper } from 'instasave-sdk';
+
+const scraper = new MediaScraper();
+const data = await scraper.scrape('https://www.instagram.com/p/ABC123/');
+
+console.log(`Post by @${data.profile_name}`);
+console.log(`${data.media.length} images found`);
+console.log(`${data.metadata.likesCount} likes`);
+```
+
+### With Authentication
+```typescript
+const scraper = new MediaScraper();
+
+await scraper.login({
+  username: 'your_username',
+  password: 'your_password'
+});
+
+const data = await scraper.scrape('https://www.instagram.com/p/private_post/', {
+  saveToFile: true,
+  outputPath: './downloads'
+});
+```
+
+### Batch Processing
+```typescript
+const urls = [
+  'https://www.instagram.com/p/ABC123/',
+  'https://www.instagram.com/p/DEF456/',
+  'https://www.instagram.com/p/GHI789/'
+];
+
+for (const url of urls) {
+  try {
+    const data = await scraper.scrape(url, { 
+      saveToFile: true,
+      timeout: 90 
+    });
+    console.log(`✅ ${data.post_id}: ${data.media.length} images`);
+  } catch (error) {
+    console.log(`❌ ${url}: ${error.message}`);
+  }
+}
+  outputPath?: string;     // Output directory path
+  headless?: boolean;      // Headless mode (default: true)
+  timeout?: number;        // Timeout in seconds (default: 60)
+  retries?: number;        // Retry attempts (default: 0)
+}
+```
+
+## Environment Variables
+
+Create `.env` file:
+```bash
+PUPPETEER_EXECUTABLE_PATH=/path/to/chromium
+HEADLESS=true
+TIMEOUT=120
+RETRIES=0
+```
+
+## Testing
+
+```bash
+# Unit tests
+npm test
+
+# Integration test (real scraping)
+npm run test:integration
+
+# Example usage
+node example.js
+```
+
+## Error Handling
+
+```typescript
+try {
+  const data = await scraper.scrapePost(url);
+} catch (error) {
+  if (error.message.includes('Invalid Instagram post URL')) {
+    // Handle invalid URL
+  } else if (error.message.includes('Failed to extract post ID')) {
+    // Handle extraction failure
+  }
+}
+```
+
+## Workflow System
+
+Plugin uses workflow automation for:
+- Closing cookie modals
+- Closing authentication modals
+- Fallback text-based clicking
+
+Workflow configuration: `workflows/instagram.wf`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instasave-sdk",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Instagram image scraper SDK with authentication support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,8 @@
   "files": [
     "dist/",
     "README.md",
+    "README_API.md",
+    "CHANGELOG.md",
     "LICENSE",
     "install-browser.js",
     "instasave.config.example"