ultra-igdl 1.0.1 → 1.0.3

package/README.md

@@ -1,269 +1,229 @@
 # ultra-igdl
 
-**Production-grade Instagram media extractor for Node.js 20+**
+**Beginner-friendly Instagram media extractor for Node.js**
 
-Fetch direct CDN URLs for reels, posts, carousels, stories, and highlights. Built from scratch with a multi-layer HTML/JSON parser, optional logged-in session API, connection pooling, LRU cache, and a CLI — **no wrapper around other Instagram downloader packages**.
+Get direct download links (images and videos) from Instagram posts, reels, carousels, stories, and highlights. Use it from the **command line** or inside your **JavaScript / TypeScript** app.
 
----
-
-## Table of contents
+[![npm version](https://img.shields.io/npm/v/ultra-igdl.svg)](https://www.npmjs.com/package/ultra-igdl)
 
-1. [Who is this for?](#who-is-this-for)
-2. [Requirements](#requirements)
-3. [Installation](#installation)
-4. [Quick start (beginner)](#quick-start-beginner)
-5. [Instagram session (important)](#instagram-session-important)
-6. [CLI guide](#cli-guide)
-7. [Supported URLs](#supported-urls)
-8. [Response format](#response-format)
-9. [Content types explained](#content-types-explained)
-10. [JavaScript / TypeScript API](#javascript--typescript-api)
-11. [Configuration options](#configuration-options)
-12. [Pro features](#pro-features)
-13. [Error codes & troubleshooting](#error-codes--troubleshooting)
-14. [Examples in this repo](#examples-in-this-repo)
-15. [Architecture](#architecture)
-16. [Development](#development)
-17. [Publishing to npm](#publishing-to-npm)
-18. [Legal & disclaimer](#legal--disclaimer)
-19. [License](#license)
+**Links:** [npm package](https://www.npmjs.com/package/ultra-igdl) · [GitHub](https://github.com/WH173-5P1D3R/ultra-igdl) · [Report issues](https://github.com/WH173-5P1D3R/ultra-igdl/issues)
 
 ---
 
-## Who is this for?
+## Table of contents
 
-| Level | You can… |
-|--------|-----------|
-| **Beginner** | Install with npm, run `npx ultra-igdl <url> --json`, paste a browser cookie for full carousels |
-| **Intermediate** | Use `ultraigdl` in Express/Fastify bots, batch URLs, download files with `--download` |
-| **Pro** | Tune cache/Redis, `fastMode` + `prefetch`, `maxConcurrency`, integrate `DownloaderCore` |
+1. [What does this do?](#1-what-does-this-do)
+2. [Who is this for?](#2-who-is-this-for)
+3. [Before you start (requirements)](#3-before-you-start-requirements)
+4. [Install Node.js and the package](#4-install-nodejs-and-the-package)
+5. [Your first download (CLI)](#5-your-first-download-cli)
+6. [Your first download (code)](#6-your-first-download-code)
+7. [Understanding the JSON response](#7-understanding-the-json-response)
+8. [Instagram session — why and how](#8-instagram-session--why-and-how)
+9. [Content types (posts, reels, carousels, stories)](#9-content-types-posts-reels-carousels-stories)
+10. [Command line (CLI) — full guide](#10-command-line-cli--full-guide)
+11. [JavaScript / TypeScript API](#11-javascript--typescript-api)
+12. [Configuration options](#12-configuration-options)
+13. [Batch URLs and bots](#13-batch-urls-and-bots)
+14. [Error codes and fixes](#14-error-codes-and-fixes)
+15. [FAQ and troubleshooting](#15-faq-and-troubleshooting)
+16. [Examples in this repository](#16-examples-in-this-repository)
+17. [Legal and privacy](#17-legal-and-privacy)
+18. [License](#18-license)
 
 ---
 
-## Requirements
+## 1. What does this do?
 
-- **Node.js** 20.18.1+ or 22 (LTS recommended)
-- **npm** 9+ (or pnpm/yarn)
-- Public Instagram URLs (no login required for basic post/reel preview)
-- **Optional:** Instagram `sessionid` cookie for carousels (all slides), reel MP4, stories, highlights
+You give **ultra-igdl** an Instagram link. It returns:
 
----
+- **Direct media URLs** (CDN links you can open or save)
+- **Caption** and **username**
+- Optional **likes / comments** counts when Instagram shows them
+- Hints in `tags` (for example: carousel detected, session recommended)
 
-## Installation
+It works **without logging in** for many public posts and reels, but Instagram limits logged-out access. For **full carousels**, **reel video files**, **stories**, and **highlights**, you usually need a **browser session cookie** (explained in [section 8](#8-instagram-session--why-and-how)).
 
-### npm (recommended)
+---
 
-```bash
-npm install ultra-igdl
-```
+## 2. Who is this for?
 
-[![npm version](https://img.shields.io/npm/v/ultra-igdl.svg)](https://www.npmjs.com/package/ultra-igdl)
+| You are… | Start here |
+|----------|------------|
+| **Complete beginner** | [Section 4](#4-install-nodejs-and-the-package) → [Section 5](#5-your-first-download-cli) (CLI with `npx`) |
+| **JavaScript developer** | [Section 6](#6-your-first-download-code) → [Section 11](#11-javascript--typescript-api) |
+| **Bot builder** (Telegram, Discord, etc.) | [Section 8](#8-instagram-session--why-and-how) + [Section 13](#13-batch-urls-and-bots) |
+| **TypeScript user** | [Section 11](#11-javascript--typescript-api) (types included) |
 
-### GitHub Packages
+No Instagram API key is required. You only need Node.js and a valid Instagram URL.
 
-Scoped package: `@wh173-5p1d3r/ultra-igdl` (published on release tags `v*`).
+---
 
-1. Create a [GitHub PAT](https://github.com/settings/tokens) with `read:packages`.
-2. Add `.npmrc` (see [`.npmrc.github.example`](./.npmrc.github.example)):
+## 3. Before you start (requirements)
 
-```ini
-@wh173-5p1d3r:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-```
+| Requirement | Details |
+|-------------|---------|
+| **Node.js** | Version **20.18.1 or newer** (22 LTS is fine). Check with `node -v` |
+| **npm** | Comes with Node. Check with `npm -v` |
+| **Instagram URL** | A normal link you can open in a browser (post, reel, story, etc.) |
+| **Session cookie** | Optional but strongly recommended for carousels, reel MP4, stories |
 
-3. Install:
+**Check Node version:**
 
 ```bash
-npm install @wh173-5p1d3r/ultra-igdl
+node -v
+# Should print v20.18.1 or higher (e.g. v22.x.x)
 ```
 
-```js
-import { ultraigdl } from "@wh173-5p1d3r/ultra-igdl";
-```
-
-Package page: https://github.com/WH173-5P1D3R/ultra-igdl/packages
-
-CLI only (no install into project):
-
-```bash
-npx ultra-igdl --help
-```
+If Node is too old, install the latest LTS from [https://nodejs.org](https://nodejs.org).
 
 ---
 
-## Quick start (beginner)
+## 4. Install Node.js and the package
 
-### 1. Programmatic (ESM)
-
-```js
-import { ultraigdl } from "ultra-igdl";
-
-const ig = new ultraigdl();
-const result = await ig.download("https://www.instagram.com/reel/SHORTCODE/");
+### Option A — Use without installing (fastest try)
 
-if (result.code === 200) {
-  console.log("User:", result.username);
-  console.log("Caption:", result.caption);
-  console.log("Files:", result.media.length);
-  result.media.forEach((m, i) => console.log(i + 1, m.type, m.url));
-} else {
-  console.error(result.code, result.message);
-}
+```bash
+npx ultra-igdl --help
 ```
 
-### 2. CommonJS
+`npx` downloads the tool temporarily and runs it. Good for a quick test.
 
-```js
-const { ultraigdl } = require("ultra-igdl");
-
-(async () => {
-  const ig = new ultraigdl();
-  const result = await ig.download("https://www.instagram.com/p/SHORTCODE/");
-  console.log(result);
-})();
-```
-
-### 3. CLI (JSON)
+### Option B — Add to your project (recommended for apps)
 
 ```bash
-npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
+mkdir my-ig-downloader
+cd my-ig-downloader
+npm init -y
+npm install ultra-igdl
 ```
 
-On **Windows PowerShell**, always wrap URLs in **double quotes** (see [CLI guide](#cli-guide)).
+You can then `import` or `require` it in your code (see [section 6](#6-your-first-download-code)).
 
 ---
 
-## Instagram session (important)
+## 5. Your first download (CLI)
 
-Instagram limits what **logged-out** visitors see:
+### Step 1 — Copy an Instagram URL
 
-| Feature | Without session | With session (`sessionId` / `cookies`) |
-|---------|-----------------|----------------------------------------|
-| Single post image | Usually yes | Yes (full resolution) |
-| **Carousel (2+ photos)** | Often **1 slide only** | **All slides** |
-| **Reel MP4** | Often thumbnail only | **Video URL** |
-| **Story** | Usually fails / preview | **Media URL** |
-| **Highlight** | Limited | **Video** when available |
+Example (replace with a real public post):
 
-### How to get cookies (browser)
+```text
+https://www.instagram.com/p/SHORTCODE/
+```
 
-1. Log in to [instagram.com](https://www.instagram.com) in Chrome/Edge/Firefox.
-2. Open DevTools → **Application** → **Cookies** → `https://www.instagram.com`.
-3. Copy:
-   - `sessionid`
-   - `csrftoken`
-   - `ds_user_id`
+### Step 2 — Run the CLI
 
-### Option A — full cookie string (recommended)
+**Linux / macOS / Git Bash:**
 
-```js
-const ig = new ultraigdl({
-  cookies:
-    "sessionid=YOUR_ID; csrftoken=YOUR_CSRF; ds_user_id=YOUR_USER_ID",
-});
+```bash
+npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/"
 ```
 
-### Option B — session id only
+**Windows PowerShell** — always put the URL in **double quotes**:
 
-```js
-const ig = new ultraigdl({
-  sessionId: "YOUR_SESSIONID_VALUE",
-});
+```powershell
+npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/"
 ```
 
-### Environment variables (CLI)
+### Step 3 — Read the output
 
-The CLI auto-loads `.env` from the current directory or `../ultra-igdl-live-test/.env`.
+Without `--json`, you get a short summary: username, caption preview, and a list of media items with type and URL.
+
+For **machine-readable output** (scripts, bots):
 
 ```bash
-# Linux / macOS
-export INSTAGRAM_COOKIES="sessionid=...; csrftoken=...; ds_user_id=..."
 npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
 ```
 
-```powershell
-# Windows PowerShell — use TWO lines, or semicolon before npx
-$env:INSTAGRAM_COOKIES = "sessionid=...; csrftoken=...; ds_user_id=..."
-npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
+### Step 4 — Save files to disk
+
+```bash
+npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --download --output ./downloads
 ```
 
-**Never commit real cookies to git.** Add `.env` to `.gitignore` (already included).
+Files go under `./downloads/<username>/`.
 
 ---
 
-## CLI guide
+## 6. Your first download (code)
 
-```bash
-npx ultra-igdl <url> [options]
-npx ultra-igdl urls.txt          # one URL per line
-```
+Create a file `test.mjs` in your project folder (after `npm install ultra-igdl`).
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--json` | `-j` | Print full API response as JSON |
-| `--download` | `-d` | Save media files under `--output` |
-| `--output <dir>` | `-o` | Download folder (default: `./downloads`) |
-| `--verbose` | `-v` | Debug logging |
-| `--help` | `-h` | Show help |
+### ESM (modern Node — `"type": "module"` in package.json, or `.mjs` file)
 
-### PowerShell rules
+```js
+import { ultraigdl } from "ultra-igdl";
 
-1. Wrap URLs in `"quotes"` when the link contains `&` (e.g. `?igsh=...&...`).
-2. Set env vars on **line 1**, run `npx` on **line 2**, **or** use `;` between them:
+const ig = new ultraigdl();
+const url = "https://www.instagram.com/reel/SHORTCODE/";
 
-```powershell
-$env:INSTAGRAM_COOKIES = "sessionid=...; csrftoken=...; ds_user_id=..."; npx ultra-igdl "https://www.instagram.com/p/ABC/" --json
+const result = await ig.download(url);
+
+if (result.code === 200) {
+  console.log("Creator:", result.username);
+  console.log("Caption:", result.caption);
+  console.log("Number of files:", result.media.length);
+  for (const item of result.media) {
+    console.log(item.type, item.url);
+  }
+} else {
+  console.log("Failed:", result.code, result.message);
+}
 ```
 
-### CLI examples
+Run:
 
 ```bash
-# Human-readable summary
-npx ultra-igdl "https://www.instagram.com/reel/ABC123/"
+node test.mjs
+```
 
-# JSON for scripts
-npx ultra-igdl "https://www.instagram.com/p/ABC123/" --json
+### CommonJS (`.cjs` file or no `"type": "module"`)
 
-# Download all carousel images
-npx ultra-igdl "https://www.instagram.com/p/ABC123/" --download -o ./downloads
+```js
+const { ultraigdl } = require("ultra-igdl");
 
-# Batch file (urls.txt)
-npx ultra-igdl urls.txt --json
+(async () => {
+  const ig = new ultraigdl();
+  const result = await ig.download("https://www.instagram.com/p/SHORTCODE/");
+  console.log(JSON.stringify(result, null, 2));
+})();
 ```
 
----
+### Handle success vs error (important pattern)
 
-## Supported URLs
+Every call returns an object with a **`code`** field:
 
-| Type | Example pattern |
-|------|-----------------|
-| Post | `https://www.instagram.com/p/{shortcode}/` |
-| Reel | `https://www.instagram.com/reel/{shortcode}/` |
-| IGTV | `https://www.instagram.com/tv/{shortcode}/` |
-| Story | `https://www.instagram.com/stories/{username}/{storyId}/` |
-| Highlight (path) | `https://www.instagram.com/stories/highlights/{id}/` |
-| Highlight (share) | `https://www.instagram.com/s/{token}?story_media_id=...` |
-
-Validate before download:
+- **`200`** — success; use `media`, `caption`, `username`
+- **Anything else** — error; read `message`
 
 ```js
-const { valid, type, normalized } = await ig.validate(url);
+const result = await ig.download(url);
+if (result.code !== 200) {
+  throw new Error(`${result.code}: ${result.message}`);
+}
+// TypeScript: narrow with if (result.code === 200) { ... result.media }
 ```
 
 ---
 
-## Response format
+## 7. Understanding the JSON response
 
-### Success (`code: 200`)
+### Successful response (`code: 200`)
 
 ```json
 {
   "code": 200,
-  "meta": { "extractor": "ultra-igdl", "version": "1.0.0" },
+  "meta": {
+    "extractor": "ultra-igdl",
+    "version": "1.0.2"
+  },
+  "username": "creator",
+  "caption": "Post caption as one clean line",
   "media": [
     {
       "type": "image",
-      "url": "https://...cdninstagram.../....jpg",
+      "url": "https://...cdninstagram.com/....jpg",
       "width": 1440,
       "height": 1800
     },
@@ -276,8 +236,6 @@ const { valid, type, normalized } = await ig.validate(url);
       "duration": 24
     }
   ],
-  "caption": "Post caption as a single clean line for posts",
-  "username": "creator",
   "engagement": {
     "likes": 1200,
     "comments": 45
@@ -286,190 +244,392 @@ const { valid, type, normalized } = await ig.validate(url);
 }
 ```
 
-### Media object
+### Media object fields
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `"image"` \| `"video"` | Primary media type |
-| `url` | `string` | Direct CDN URL (signed; do not edit query params) |
-| `thumbnail` | `string?` | Poster frame for video |
-| `width` / `height` | `number?` | Pixel dimensions when known |
-| `duration` | `number?` | Video length in seconds |
+| Field | Meaning |
+|-------|---------|
+| `type` | `"image"` or `"video"` |
+| `url` | Direct link to the file (use as-is; do not remove `?` parameters) |
+| `thumbnail` | Preview image for videos |
+| `width` / `height` | Pixel size when known |
+| `duration` | Video length in seconds |
 
-### Tags (`tags` array)
+### Tags (`tags` array) — what they mean for you
 
-| Tag | Meaning |
-|-----|---------|
-| `carousel` | Multi-slide post; `media.length` ≥ 2 |
-| `partial_carousel` | Carousel detected but only one slide returned |
-| `session_recommended` | Add `sessionId` / `cookies` for full carousel |
-| `likes_hidden` | Creator hid like counts |
-| `comments_hidden` | Comments disabled or hidden |
-| `engagement_hidden` | Both likes and comments hidden |
+| Tag | Meaning | What you should do |
+|-----|---------|-------------------|
+| `carousel` | Multi-photo post; all slides returned | Nothing — you got the full carousel |
+| `partial_carousel` | Carousel detected but only one image returned | Add session cookies ([section 8](#8-instagram-session--why-and-how)) |
+| `session_recommended` | Logged-in session would improve results | Add `cookies` or `sessionId` |
+| `likes_hidden` | Creator hid like counts | Normal — not an error |
+| `comments_hidden` | Comments hidden or disabled | Normal — not an error |
+| `engagement_hidden` | Both hidden | Normal — not an error |
 
-### Error (`code` ≠ 200)
+### Error response (`code` not 200)
 
 ```json
 {
   "code": 404,
   "message": "Media not found",
-  "meta": { "extractor": "ultra-igdl", "version": "1.0.0" }
+  "meta": { "extractor": "ultra-igdl", "version": "1.0.2" }
 }
 ```
 
-Some responses include `retryAfterMs` when using `fastMode` / `responseBudgetMs` (background fetch still running).
+Some responses include `retryAfterMs` when using fast-response mode ([section 13](#13-batch-urls-and-bots)).
 
 ---
 
-## Content types explained
+## 8. Instagram session — why and how
+
+Instagram shows **less content** to visitors who are not logged in.
 
-### Posts (single image)
+| Feature | Without session | With session (`cookies` / `sessionId`) |
+|---------|-----------------|--------------------------------------|
+| Single post image | Usually works | Works (often higher resolution) |
+| **Carousel (2+ photos)** | Often **only 1 slide** | **All slides** |
+| **Reel MP4 video** | Often thumbnail only | **Full video URL** |
+| **Story** | Usually fails or preview only | **Works** (if story is still live) |
+| **Highlight** | Limited | More reliable |
+
+### How to get cookies (Chrome / Edge / Firefox)
+
+1. Open [https://www.instagram.com](https://www.instagram.com) and **log in**.
+2. Press **F12** to open Developer Tools.
+3. Go to **Application** (Chrome) or **Storage** (Firefox) → **Cookies** → `https://www.instagram.com`.
+4. Copy these values:
+   - `sessionid`
+   - `csrftoken`
+   - `ds_user_id`
+
+**Treat these like a password.** Never post them on GitHub, Discord, or screenshots.
+
+### Use in code — full cookie string (recommended)
+
+```js
+const ig = new ultraigdl({
+  cookies:
+    "sessionid=YOUR_SESSIONID; csrftoken=YOUR_CSRF; ds_user_id=YOUR_USER_ID",
+});
+```
+
+### Use in code — session id only
+
+```js
+const ig = new ultraigdl({
+  sessionId: "YOUR_SESSIONID_VALUE",
+});
+```
+
+### Use with environment variables (CLI and scripts)
+
+Create a `.env` file in your project folder (add `.env` to `.gitignore`):
+
+```env
+INSTAGRAM_COOKIES=sessionid=xxx; csrftoken=xxx; ds_user_id=xxx
+```
+
+Or only:
+
+```env
+INSTAGRAM_SESSION_ID=your_sessionid_value
+```
+
+The CLI loads `.env` from the current directory automatically.
+
+**Linux / macOS terminal:**
+
+```bash
+export INSTAGRAM_COOKIES="sessionid=...; csrftoken=...; ds_user_id=..."
+npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
+```
+
+**Windows PowerShell** — use **two lines** (or semicolon before `npx`):
+
+```powershell
+$env:INSTAGRAM_COOKIES = "sessionid=...; csrftoken=...; ds_user_id=..."
+npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
+```
+
+One-line PowerShell alternative:
+
+```powershell
+$env:INSTAGRAM_COOKIES = "sessionid=...; csrftoken=...; ds_user_id=..."; npx ultra-igdl "https://www.instagram.com/p/SHORTCODE/" --json
+```
+
+### Load cookies from `process.env` in Node
+
+```js
+const ig = new ultraigdl({
+  cookies: process.env.INSTAGRAM_COOKIES,
+});
+```
+
+---
+
+## 9. Content types (posts, reels, carousels, stories)
+
+### Supported URL patterns
+
+| Type | URL pattern |
+|------|-------------|
+| Post | `https://www.instagram.com/p/{shortcode}/` |
+| Reel | `https://www.instagram.com/reel/{shortcode}/` |
+| IGTV | `https://www.instagram.com/tv/{shortcode}/` |
+| Story | `https://www.instagram.com/stories/{username}/{storyId}/` |
+| Highlight | `https://www.instagram.com/stories/highlights/{id}/` |
+| Highlight share link | `https://www.instagram.com/s/{token}?story_media_id=...` |
+
+### Single-image post
 
 ```js
 const result = await ig.download("https://www.instagram.com/p/SHORTCODE/");
-// result.media.length === 1 typically
+// result.media.length is often 1
 ```
 
-### Carousels (2+ photos)
+### Carousel (multiple photos)
 
-- **Auto-detected** from any `/p/` URL — no special URL or env var.
-- Without session: often 1 image + tags `partial_carousel`, `session_recommended`.
-- With session: all slides, tag `carousel`.
+Same URL as a normal post (`/p/...`). No special mode — the library detects carousels automatically.
 
 ```js
 const ig = new ultraigdl({ cookies: process.env.INSTAGRAM_COOKIES });
 const result = await ig.download("https://www.instagram.com/p/SHORTCODE/");
-console.log(result.media.length); // e.g. 4
-console.log(result.tags);         // ["carousel"]
+console.log("Slides:", result.media.length);
+console.log("Tags:", result.tags);
 ```
 
-### Reels
+If you see `partial_carousel` or `session_recommended`, add cookies from [section 8](#8-instagram-session--why-and-how).
+
+### Reel (video)
 
 ```js
 const ig = new ultraigdl({ sessionId: process.env.INSTAGRAM_SESSION_ID });
 const result = await ig.download("https://www.instagram.com/reel/SHORTCODE/");
 const video = result.media.find((m) => m.type === "video");
+if (video) console.log("MP4:", video.url);
 ```
 
-### Stories
+### Story
 
-Requires session. Story must still be live (not expired).
+Requires session. The story must still be **live** (not expired after 24 hours).
 
 ```js
+const ig = new ultraigdl({ cookies: process.env.INSTAGRAM_COOKIES });
 const result = await ig.download(
-  "https://www.instagram.com/stories/username/1234567890/"
+  "https://www.instagram.com/stories/username/1234567890123456789/"
 );
 ```
 
-### Highlights
+### Check a URL before downloading
+
+```js
+const check = await ig.validate("https://www.instagram.com/p/SHORTCODE/");
+console.log(check.valid, check.type, check.normalized);
+```
+
+Or use the exported helper:
 
-Works with highlight URLs or `/s/` share links; session improves reliability.
+```js
+import { validateUrl, parseInstagramUrl, isInstagramUrl } from "ultra-igdl";
+
+console.log(isInstagramUrl(url));
+console.log(parseInstagramUrl(url));
+console.log(validateUrl(url));
+```
 
 ---
 
-## JavaScript / TypeScript API
+## 10. Command line (CLI) — full guide
+
+### Basic usage
+
+```bash
+npx ultra-igdl "<instagram-url>"
+npx ultra-igdl "<instagram-url>" --json
+npx ultra-igdl "<instagram-url>" --download
+npx ultra-igdl "<instagram-url>" --download --output ./my-folder
+npx ultra-igdl "<instagram-url>" --verbose
+```
+
+### Batch file (many URLs)
+
+Create `urls.txt` — one URL per line. Lines starting with `#` are ignored.
+
+```text
+https://www.instagram.com/p/ABC123/
+https://www.instagram.com/reel/DEF456/
+```
+
+Run:
+
+```bash
+npx ultra-igdl urls.txt --json
+```
+
+### All CLI flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--json` | `-j` | Print full API JSON |
+| `--download` | `-d` | Save media files to disk |
+| `--output <dir>` | `-o` | Download folder (default: `./downloads`) |
+| `--verbose` | `-v` | Debug logging |
+| `--help` | `-h` | Show help |
+
+### Environment variables (CLI)
+
+| Variable | Purpose |
+|----------|---------|
+| `INSTAGRAM_COOKIES` | Full cookie string (`sessionid=...; csrftoken=...; ...`) |
+| `INSTAGRAM_SESSION_ID` | Just the `sessionid` value |
+
+### PowerShell tips (Windows)
+
+1. **Always quote URLs** that contain `&` (shared links with `?igsh=...&...`).
+2. Setting env vars and running `npx` on the **same line** requires a semicolon:
+
+```powershell
+$env:INSTAGRAM_COOKIES = "sessionid=..."; npx ultra-igdl "https://www.instagram.com/p/ABC/" --json
+```
+
+3. If you see errors about `npx` or `Unexpected token`, run env and `npx` on **separate lines**.
+
+---
+
+## 11. JavaScript / TypeScript API
+
+### Create an instance
 
 ```ts
 import { ultraigdl, type ApiResponse, type DownloadResponse } from "ultra-igdl";
 
-const ig = new ultraigdl({ cache: true, retries: 2 });
+const ig = new ultraigdl({
+  cache: true,
+  retries: 2,
+  cookies: process.env.INSTAGRAM_COOKIES,
+});
 ```
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `download(url)` | `Promise<ApiResponse>` | Full extraction (main method) |
-| `info(url)` | `Promise<ApiResponse>` | Alias of `download` |
-| `validate(url)` | `Promise<{ valid, type?, normalized? }>` | URL check + normalization |
-| `media(url)` | `Promise<Media[] \| ErrorResponse>` | Media array only |
-| `batch(urls)` | `Promise<BatchResult[]>` | Parallel downloads with per-URL timing |
-| `prefetch(url)` | `Promise<ApiResponse>` | Warm cache for `fastMode` |
-| `health()` | `Promise<HealthStatus>` | Cache stats, pool, version |
-| `clearCache()` | `void` | Clear in-memory LRU cache |
+### Methods
 
-### TypeScript
+| Method | Returns | When to use |
+|--------|---------|-------------|
+| `download(url)` | `Promise<ApiResponse>` | Main method — full result |
+| `info(url)` | `Promise<ApiResponse>` | Same as `download` |
+| `validate(url)` | `Promise<{ valid, type?, normalized? }>` | Check URL before processing |
+| `media(url)` | `Promise<Media[] \| ErrorResponse>` | Only the `media` array |
+| `batch(urls)` | `Promise<BatchResult[]>` | Many URLs at once |
+| `prefetch(url)` | `Promise<ApiResponse>` | Warm cache before `download` (bots) |
+| `health()` | `Promise<HealthStatus>` | Version, cache size, connection pool |
+| `clearCache()` | `void` | Clear in-memory cache |
 
-Types are shipped in `dist/index.d.ts`. Narrow success responses:
+### TypeScript — narrow success type
 
 ```ts
 const result = await ig.download(url);
 if (result.code === 200) {
-  const data = result as DownloadResponse;
-  data.media.forEach((m) => { /* ... */ });
+  const ok = result as DownloadResponse;
+  ok.media.forEach((m) => console.log(m.url));
 }
 ```
 
-### Helpers (also exported)
+### Download files yourself (library)
+
+Use `fetch` or any HTTP client on `media[].url`, or use the CLI `--download` flag which handles saving for you.
+
+```js
+const res = await fetch(result.media[0].url);
+const buf = Buffer.from(await res.arrayBuffer());
+// write buf to disk with fs
+```
+
+**Do not modify** the CDN URL query string — links are signed and may break if edited.
+
+### Exported utilities
 
 ```ts
-import { validateUrl, parseInstagramUrl, isInstagramUrl } from "ultra-igdl";
+import {
+  ultraigdl,
+  validateUrl,
+  parseInstagramUrl,
+  isInstagramUrl,
+  PACKAGE_VERSION,
+  EXTRACTOR_NAME,
+} from "ultra-igdl";
 ```
 
+Advanced: `DownloaderCore` is exported for custom integrations.
+
 ---
 
-## Configuration options
+## 12. Configuration options
 
-```ts
+Pass these to `new ultraigdl({ ... })`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `cache` | `true` | Cache responses in memory |
+| `cacheTtlMs` | `300000` (5 min) | Fresh cache lifetime |
+| `staleCacheTtlMs` | `86400000` (24 h) | Serve stale while refreshing |
+| `cacheMaxSize` | `500` | Max cached entries |
+| `timeoutMs` | `8000` | HTTP timeout per request |
+| `retries` | `2` | Retry count on failure |
+| `maxConcurrency` | `100` | Parallel request limit |
+| `userAgentRotation` | `true` | Rotate browser user-agents |
+| `sessionId` | — | Instagram `sessionid` cookie value |
+| `cookies` | — | Full cookie header string |
+| `verbose` | `false` | Extra logging |
+| `fastMode` | `false` | Target ~500 ms response; may return 503 + retry hint |
+| `responseBudgetMs` | — | Max time for `download()` to return |
+| `redis` | — | Custom `RedisAdapter` for shared cache |
+
+Example — tuned for a small API server:
+
+```js
 const ig = new ultraigdl({
-  // Cache
-  cache: true,              // default: true
-  cacheTtlMs: 300_000,      // 5 min fresh TTL
-  staleCacheTtlMs: 86_400_000, // 24h stale-while-revalidate
-  cacheMaxSize: 500,
-
-  // Network
-  maxConcurrency: 100,
+  cache: true,
+  cacheTtlMs: 600_000,
   timeoutMs: 15_000,
   retries: 3,
-  userAgentRotation: true,
-
-  // Session
-  sessionId: "...",
-  cookies: "sessionid=...; csrftoken=...; ds_user_id=...",
-
-  // Low-latency mode (bots that reply in <500ms)
-  fastMode: true,           // sets responseBudgetMs: 500, retries: 0
-  responseBudgetMs: 800,
+  cookies: process.env.INSTAGRAM_COOKIES,
+});
+```
 
-  // Optional Redis (implement RedisAdapter interface)
-  redis: myRedisAdapter,
+Example — low-latency bot (may need retry on 503):
 
-  verbose: false,
-});
+```js
+const ig = new ultraigdl({ fastMode: true, cookies: process.env.INSTAGRAM_COOKIES });
+await ig.prefetch(url);
+let result = await ig.download(url);
+if (result.code === 503 && result.retryAfterMs) {
+  await new Promise((r) => setTimeout(r, result.retryAfterMs));
+  result = await ig.download(url);
+}
 ```
 
 ---
 
-## Pro features
+## 13. Batch URLs and bots
 
-### Batch processing
+### Batch in code
 
-```ts
+```js
 const results = await ig.batch([
   "https://www.instagram.com/p/A/",
   "https://www.instagram.com/reel/B/",
 ]);
+
 for (const { url, result, durationMs } of results) {
   console.log(url, result.code, `${durationMs}ms`);
 }
 ```
 
-### Fast mode + prefetch (Telegram/Discord bots)
+### Batch from CLI
 
-```ts
-const ig = new ultraigdl({ fastMode: true, cookies: "..." });
+Use a `.txt` file ([section 10](#10-command-line-cli--full-guide)).
 
-// Warm extraction while user types
-await ig.prefetch(url);
-
-// Often returns from cache within budget
-let result = await ig.download(url);
-if (result.code === 503 && result.retryAfterMs) {
-  await new Promise((r) => setTimeout(r, result.retryAfterMs));
-  result = await ig.download(url);
-}
-```
+### Redis cache (optional, advanced)
 
-### Redis cache adapter
+If you run multiple server instances, implement `RedisAdapter`:
 
 ```ts
 import { ultraigdl, type RedisAdapter } from "ultra-igdl";
@@ -482,141 +642,86 @@ const redis: RedisAdapter = {
 const ig = new ultraigdl({ redis });
 ```
 
-### Download files to disk (library)
-
-Use your own `fetch` on `media[].url`, or the CLI `--download` flag (uses built-in file downloader).
-
 ---
 
-## Error codes & troubleshooting
+## 14. Error codes and fixes
 
-| Code | Typical cause | What to do |
-|------|---------------|------------|
-| **400** | Invalid URL | Use `validate()`; check link format |
-| **403** | Private account | Cannot extract without access |
-| **404** | Deleted / wrong id / expired story | Verify URL in browser |
-| **429** | Rate limited | Slow down; reduce concurrency; wait |
-| **500** | Parse/network failure | Retry; update package; report issue |
-| **503** | `fastMode` budget exceeded | Retry after `retryAfterMs` or disable fast mode |
+| Code | Meaning | What to try |
+|------|---------|-------------|
+| **400** | Invalid URL | Run `validate()`; fix the link |
+| **403** | Private or blocked | Cannot access without permission |
+| **404** | Not found | Post deleted, wrong ID, or expired story |
+| **429** | Rate limited | Wait and slow down; fewer parallel requests |
+| **500** | Server / parse error | Retry; update package; open an issue |
+| **503** | Fast mode: still fetching | Wait `retryAfterMs` and call `download` again |
 | **504** | Timeout | Increase `timeoutMs` |
 
-| Symptom | Fix |
-|---------|-----|
-| Carousel returns 1 image | Set `cookies` or `sessionId` |
-| Reel has no MP4 | Add session cookie |
-| CLI `Unexpected token 'npx'` | Use `;` or two lines in PowerShell |
-| `Invalid or unexpected token` on CLI | Run `npm run build`; use published version |
-| Caption has weird dots/lines | Post captions are flattened to one line by design |
-| 403 on CDN URL when downloading | Do not modify signed URL query string |
-
 ---
 
-## Examples in this repo
-
-| File | Description |
-|------|-------------|
-| [`examples/basic.mjs`](./examples/basic.mjs) | Minimal JSON dump |
-| [`examples/bot-example.ts`](./examples/bot-example.ts) | Generic bot handler |
-| [`examples/express-api.ts`](./examples/express-api.ts) | REST API with Express |
-| [`examples/fastify-api.ts`](./examples/fastify-api.ts) | REST API with Fastify |
-| [`examples/telegram-bot.ts`](./examples/telegram-bot.ts) | Telegram-style handler |
-| [`examples/discord-bot.ts`](./examples/discord-bot.ts) | Discord-style handler |
-| [`examples/cookie-generator.mjs`](./examples/cookie-generator.mjs) | Cookie helper notes |
-
-Run locally after build:
+## 15. FAQ and troubleshooting
 
-```bash
-npm run build
-node examples/basic.mjs "https://www.instagram.com/p/SHORTCODE/"
-```
+**Q: Carousel only returns one image.**  
+A: Add `INSTAGRAM_COOKIES` or `sessionId` ([section 8](#8-instagram-session--why-and-how)).
 
-**Live Instagram tests** are kept in a separate repo folder: `ultra-igdl-live-test` (not published to npm).
+**Q: Reel has no video, only thumbnail.**  
+A: Same — use a logged-in session cookie.
 
----
+**Q: Story returns 404.**  
+A: Stories expire after 24 hours, or the URL is wrong. Session is required.
 
-## Architecture
+**Q: CLI works on Mac but fails on PowerShell.**  
+A: Quote the URL; set env vars on a separate line or use `;` before `npx`.
 
-```
-src/
-├── core/           # downloader orchestration, cache, parser, extractor
-├── extractors/     # post, reel, story, highlight
-├── network/        # undici client, headers, retry, pool, Instagram API
-├── utils/          # captions, carousel, media quality, URLs
-├── cli/            # CLI entry (published as ultra-igdl bin)
-└── types/          # TypeScript definitions
-```
+**Q: Downloaded file from CDN is corrupt or 403.**  
+A: Copy the `url` exactly from the API response. Do not strip query parameters.
 
-**Extraction layers** (first useful result wins, posts scan multiple layers for carousels):
+**Q: Caption looks like one long line.**  
+A: Post captions are normalized to a single clean line by design (engagement text is in `engagement`, not `caption`).
 
-1. Open Graph / meta tags  
-2. Embedded `application/json` / script blobs  
-3. `window.__additionalDataLoaded` / `_sharedData`  
-4. Next.js `__NEXT_DATA__`  
-5. GraphQL / CDN discovery in HTML  
-6. Regex fallback  
+**Q: How do I update?**  
+A: `npm update ultra-igdl` or bump version in `package.json` and run `npm install`.
 
-With **session**: parallel `media/info` API for posts (carousels), reels, stories, highlights.
+**Q: Does this need an Instagram API key?**  
+A: No. It uses the same kind of page parsing and optional session API as a logged-in browser.
 
 ---
 
-## Development
+## 16. Examples in this repository
 
-```bash
-git clone https://github.com/your-username/ultra-igdl.git
-cd ultra-igdl
-npm install
-npm run build
-npm test
-npm run test:coverage
-npm run test:stress
-```
-
-| Script | Purpose |
-|--------|---------|
-| `npm run build` | Compile ESM + CJS + CLI to `dist/` |
-| `npm test` | Unit + integration tests (mocked HTTP; excludes stress) |
-| `npm run cli -- "<url>" --json` | Run CLI from source tree |
-| `npm run lint` | Typecheck |
+After cloning, build once: `npm run build`.
 
----
-
-## Publishing to npm
+| File | What it shows |
+|------|----------------|
+| [`examples/basic.mjs`](./examples/basic.mjs) | Minimal JSON output |
+| [`examples/bot-example.ts`](./examples/bot-example.ts) | Generic bot handler |
+| [`examples/express-api.ts`](./examples/express-api.ts) | REST API with Express |
+| [`examples/fastify-api.ts`](./examples/fastify-api.ts) | REST API with Fastify |
+| [`examples/telegram-bot.ts`](./examples/telegram-bot.ts) | Telegram-style flow |
+| [`examples/discord-bot.ts`](./examples/discord-bot.ts) | Discord-style flow |
+| [`examples/cookie-generator.mjs`](./examples/cookie-generator.mjs) | Cookie setup notes |
 
-Maintainers:
+Run basic example:
 
 ```bash
-# 1. Login
-npm login
-
-# 2. Set author/repository in package.json (your GitHub username)
-
-# 3. Dry run — only dist/, README, LICENSE should be listed
-npm pack --dry-run
-
-# 4. Publish (runs build + tests via prepublishOnly)
-npm publish
+npm run build
+node examples/basic.mjs "https://www.instagram.com/p/SHORTCODE/"
 ```
 
-Consumers install with:
+---
 
-```bash
-npm install ultra-igdl
-```
+## 17. Legal and privacy
 
-**Before first publish:** change `repository`, `bugs`, and `homepage` in `package.json` from `your-username` to your real GitHub path.
+- **Not affiliated** with Instagram or Meta.
+- You must follow **Instagram’s Terms of Use** and your local laws. Only download content you are allowed to use.
+- **Session cookies are credentials** — never commit them, share them publicly, or log them in production.
+- CDN URLs are **temporary signed links** — download soon; do not alter the URL.
 
 ---
 
-## Legal & disclaimer
+## 18. License
 
-- This project is **not affiliated with Instagram / Meta**.
-- You are responsible for complying with Instagram's Terms of Use and applicable laws.
-- Only download content you have the right to access and use.
-- Session cookies are credentials — treat them like passwords.
-- CDN URLs are **signed** and expire; download promptly and do not strip query parameters.
+[MIT](./LICENSE) — free to use with attribution.
 
 ---
 
-## License
-
-[MIT](./LICENSE) © 2026 ultra-igdl contributors
+**Need help?** Open an issue: [github.com/WH173-5P1D3R/ultra-igdl/issues](https://github.com/WH173-5P1D3R/ultra-igdl/issues)