@kazedevid/tiktok-sup 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# tiktok-sup 🚀
+# @kazedevid/tiktok-sup 🚀
 
-> **Pure TikTok Web Scraper for Node.js** — Scrapes video metadata, direct MP4 streams, MP3 audio, user profiles, comments, and trending hashtags directly from `tiktok.com`. **100% pure web scraping with zero 3rd-party APIs or proxies.**
+> **Pure TikTok Web Scraper for Node.js (v1.1.0)** — Scrapes video metadata, direct no-watermark MP4 streams, MP3 audio, user profiles, comments, hashtags, and trending topics directly from `tiktok.com`. **100% pure web scraping with zero 3rd-party APIs, zero external proxies, and zero heavy browser automation.**
 
-[![npm version](https://img.shields.io/npm/v/tiktok-sup.svg?style=flat-square&color=cb0000)](https://www.npmjs.com/package/tiktok-sup)
+[![npm version](https://img.shields.io/npm/v/@kazedevid/tiktok-sup.svg?style=flat-square&color=cb0000)](https://www.npmjs.com/package/@kazedevid/tiktok-sup)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![GitHub](https://img.shields.io/badge/GitHub-KazeDevID%2Ftiktok--sup-black?style=flat-square&logo=github)](https://github.com/KazeDevID/tiktok-sup)
 
@@ -10,134 +10,131 @@
 
 ## ✨ Features
 
-- 🎯 **Pure tiktok.com scraping** — Zero reliance on rapidapi, tikwm, ssstik, or external proxies.
-- ⚡ **Lightning Fast** — Direct lightweight parsing of TikTok mobile SSR rehydration & web data.
-- 🎬 **Video & Photo Slides** — Supports standard video posts, short links (`vt.tiktok.com`, `vm.tiktok.com`), and multi-image photo carousels.
-- 🎵 **Audio / Music Extractor** — Extract sound titles, author names, durations, and direct audio stream URLs.
-- 👤 **Full User Profile Scraper** — Followers, following count, total likes/hearts, video counts, bio, secUid, and verified badges.
-- 💬 **Comments Extractor** — Scrapes initial comment lists directly from the post data.
-- 📈 **Trending Explorer** — Discovers trending creators, hashtags, and viral sounds.
-- 🛡️ **Session Cookie Handling** — Returns session cookies required to stream video and audio directly from TikTok CDN.
-- 📦 **TypeScript Support** — Full type definitions out of the box.
-- 💻 **CLI Included** — Run directly via `npx tiktok-sup` in your terminal.
+- 🎯 **100% Pure tiktok.com Scraping** — Zero reliance on rapidapi, tikwm, ssstik, or external proxies.
+- ⚡ **Multi-Strategy Parser** — Extracts mobile reflow data, JSON payloads, and session cookies automatically.
+- 🎬 **No-Watermark & Watermark Streams** — Provides `noWatermarkUrl` (direct playAddr) and standard `watermarkUrl`.
+- 🖼️ **Photo Slideshows** — Full resolution photo carousel images extractor.
+- 🎵 **Soundtrack Audio Extractor** — Direct MP3 play URLs, durations, and album artwork.
+- 👤 **Full User Profile Scraper** — Followers, following, total hearts/likes, video count, bio link, secUid, and verified checkmarks.
+- 💬 **Comments Extractor** — Parses initial comments list directly from the post payload.
+- 📈 **Trending & Discover** — Real-time creators, viral hashtags with view counts, and popular audio tracks.
+- 📥 **Built-in Downloader** — Helpers `downloadFile()` and `downloadBuffer()` for Telegram bots, Discord bots, and Express backends.
+- 📦 **TypeScript Ready** — Includes complete type declarations out of the box (`index.d.ts`).
+- 💻 **CLI Tool Included** — Instant terminal execution via `npx @kazedevid/tiktok-sup`.
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install tiktok-sup
+npm install @kazedevid/tiktok-sup
 ```
 
-or with yarn / pnpm:
+or with yarn / pnpm / bun:
 
 ```bash
-yarn add tiktok-sup
-# or
-pnpm add tiktok-sup
+yarn add @kazedevid/tiktok-sup
+pnpm add @kazedevid/tiktok-sup
+bun add @kazedevid/tiktok-sup
 ```
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Usage Guide
 
-### 1. Scrape Video Metadata & Stream Links
+### 1. Scrape Video & Download (No Watermark)
 
 ```javascript
-import { scrapeVideo } from 'tiktok-sup';
+import { scrapeVideo, downloadFile } from '@kazedevid/tiktok-sup';
 
-// Works with any TikTok URL (desktop, mobile, or vt.tiktok.com short links)
+// Works with full URLs, short links (vt.tiktok.com), or raw video IDs
 const video = await scrapeVideo('https://www.tiktok.com/@zachking/video/6768504823336815877');
 
-console.log('Title/Desc:', video.description);
+console.log('Title:', video.description);
 console.log('Author:', video.author.nickname, `(@${video.author.username})`);
-console.log('Stats:', video.stats); // { views, likes, comments, shares, bookmarks }
-console.log('Video Play URL:', video.video?.playUrl);
-console.log('Music:', video.music?.title, '-', video.music?.playUrl);
+console.log('Views:', video.stats.views.toLocaleString());
+console.log('Likes:', video.stats.likes.toLocaleString());
+console.log('No-Watermark URL:', video.video?.noWatermarkUrl);
+console.log('Audio Track:', video.music?.title, video.music?.playUrl);
+
+// Download directly to disk:
+const streamUrl = video.video.noWatermarkUrl || video.video.playUrl;
+await downloadFile(streamUrl, 'video_clean.mp4', video.sessionCookies);
+console.log('Downloaded clean MP4!');
 ```
 
 ### 2. Scrape User Profile
 
 ```javascript
-import { scrapeUser } from 'tiktok-sup';
+import { scrapeUser } from '@kazedevid/tiktok-sup';
 
-const profile = await scrapeUser('mrbeast');
+// Pass username with or without '@', or full profile URL
+const user = await scrapeUser('mrbeast');
 
-console.log('Name:', profile.nickname);
-console.log('Followers:', profile.stats.followerCount.toLocaleString());
-console.log('Total Likes:', profile.stats.heartCount.toLocaleString());
-console.log('Bio:', profile.signature);
-console.log('Verified:', profile.verified);
+console.log('Name:', user.nickname);
+console.log('Followers:', user.stats.followerCount.toLocaleString());
+console.log('Total Likes:', user.stats.heartCount.toLocaleString());
+console.log('Bio:', user.signature);
+console.log('secUid:', user.secUid);
 ```
 
-### 3. Explore Trending Creators & Hashtags
+### 3. Get Media Buffer (for Bots / Telegram / Discord)
 
 ```javascript
-import { scrapeTrending } from 'tiktok-sup';
+import { scrapeVideo, downloadBuffer } from '@kazedevid/tiktok-sup';
 
-const trending = await scrapeTrending();
-trending.forEach(item => {
-  console.log(`[${item.type}] ${item.title} - ${item.subTitle || ''}`);
-});
-```
+const video = await scrapeVideo('https://vt.tiktok.com/...');
+const buffer = await downloadBuffer(video.video.playUrl, video.sessionCookies);
 
-### 4. Downloading or Streaming Videos Directly
+// Send buffer to Telegram, Discord, or S3
+// bot.sendVideo(chatId, buffer);
+```
 
-TikTok CDN requires session cookies and matching referer headers to stream:
+### 4. Trending & Hashtags
 
 ```javascript
-import { scrapeVideo, fetchMediaStream } from 'tiktok-sup';
-import fs from 'fs';
-
-const video = await scrapeVideo('https://vt.tiktok.com/...');
-const streamUrl = video.video.downloadUrl || video.video.playUrl;
+import { scrapeTrending, scrapeHashtag } from '@kazedevid/tiktok-sup';
 
-// fetchMediaStream automatically attaches TikTok referer and session cookies
-const response = await fetchMediaStream(streamUrl, video.sessionCookies);
-const buffer = Buffer.from(await response.arrayBuffer());
+// Get trending items
+const trending = await scrapeTrending('all'); // 'all' | 'creator' | 'hashtag' | 'music'
 
-fs.writeFileSync('video.mp4', buffer);
-console.log('Downloaded video.mp4 successfully!');
+// Scrape hashtag stats
+const tag = await scrapeHashtag('fyp');
+console.log(tag.title, tag.views);
 ```
 
 ---
 
 ## 💻 CLI Usage
 
-You can use `tiktok-sup` directly in your terminal without writing code:
-
 ```bash
 # Scrape video info
-npx tiktok-sup video "https://www.tiktok.com/@zachking/video/6768504823336815877"
+npx @kazedevid/tiktok-sup video "https://www.tiktok.com/@zachking/video/6768504823336815877"
 
 # Scrape user profile
-npx tiktok-sup user khaby.lame
+npx @kazedevid/tiktok-sup user khaby.lame
 
-# List trending topics
-npx tiktok-sup trending
+# List trending creators & sounds
+npx @kazedevid/tiktok-sup trending
 
-# Download video MP4 directly
-npx tiktok-sup download "https://vt.tiktok.com/..." output.mp4
+# Download video directly
+npx @kazedevid/tiktok-sup download "https://vt.tiktok.com/..." clean.mp4
 ```
 
 ---
 
 ## 📚 API Reference
 
-### `scrapeVideo(url: string): Promise<TikTokVideoResult>`
-Parses full video metadata, author info, statistics, audio URLs, direct stream URLs, and comments.
-
-### `scrapeUser(username: string): Promise<TikTokUserProfile>`
-Scrapes a user profile by username handle (with or without `@`).
-
-### `scrapeTrending(): Promise<TikTokTrendingItem[]>`
-Fetches trending creators, hashtags, and sound tracks from `tiktok.com/node/share/discover`.
-
-### `parseTikTokUrl(url: string)`
-Extracts videoId and username from any format.
-
-### `fetchMediaStream(url: string, cookieStr?: string): Promise<Response>`
-Fetches the raw media buffer with TikTok headers.
+| Function | Parameters | Returns | Description |
+| :--- | :--- | :--- | :--- |
+| `scrapeVideo(url)` | `url: string` | `Promise<TikTokVideoResult>` | Scrapes full post metadata, no-watermark MP4, audio, and comments |
+| `scrapeUser(username)` | `username: string` | `Promise<TikTokUserProfile>` | Extracts creator metrics, follower count, total likes, bio, and secUid |
+| `scrapeTrending(cat)` | `category?: string` | `Promise<TikTokTrendingItem[]>` | Fetches live trending creators, hashtags, and viral sounds |
+| `scrapeHashtag(tag)` | `tag: string` | `Promise<TikTokHashtagInfo>` | Extracts view counts and info for a hashtag |
+| `scrapeSound(id)` | `soundIdOrUrl: string` | `Promise<TikTokSoundInfo>` | Scrapes soundtrack metadata and play links |
+| `downloadFile(url, out, cookies)` | `url, path, cookies?` | `Promise<string>` | Downloads media buffer directly to a local file |
+| `downloadBuffer(url, cookies)` | `url, cookies?` | `Promise<Buffer>` | Downloads media buffer directly into memory |
+| `fetchMediaStream(url, cookies)` | `url, cookies?` | `Promise<Response>` | Stream response with official TikTok headers and referer |
 
 ---
 

package/bin/cli.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 
 /**
- * tiktok-sup CLI
+ * tiktok-sup CLI (v1.1.0)
  * Command line tool for scraping TikTok without 3rd party APIs
  */
 
-import { scrapeVideo, scrapeUser, scrapeTrending } from '../index.js';
-import fs from 'fs';
-import path from 'path';
+import {
+  scrapeVideo,
+  scrapeUser,
+  scrapeTrending,
+  scrapeHashtag,
+  scrapeSound,
+  downloadFile,
+} from '../index.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -16,18 +21,21 @@ const target = args[1];
 async function main() {
   if (!command || command === '--help' || command === '-h') {
     console.log(`
-tiktok-sup - Pure TikTok Web Scraper for Node.js (tiktok.com only)
+@kazedevid/tiktok-sup - Pure TikTok Web Scraper for Node.js (tiktok.com only)
 
 Usage:
-  npx tiktok-sup video <url>            Scrape full video metadata, audio & stream links
-  npx tiktok-sup user <username>        Scrape user profile and statistics
-  npx tiktok-sup trending               List trending creators, hashtags and music
-  npx tiktok-sup download <url> [out]   Download video MP4 to file
+  npx @kazedevid/tiktok-sup video <url|id>          Scrape video metadata, no-watermark MP4 & audio
+  npx @kazedevid/tiktok-sup user <username>         Scrape user profile and statistics
+  npx @kazedevid/tiktok-sup trending [category]     List trending creators, hashtags or music
+  npx @kazedevid/tiktok-sup hashtag <tag>           Scrape hashtag info and views
+  npx @kazedevid/tiktok-sup sound <id|title>        Scrape audio track details
+  npx @kazedevid/tiktok-sup download <url> [out]    Download no-watermark MP4 to file
 
 Examples:
-  npx tiktok-sup video https://www.tiktok.com/@zachking/video/6768504823336815877
-  npx tiktok-sup user khaby.lame
-  npx tiktok-sup download https://vt.tiktok.com/ZS... ./myvideo.mp4
+  npx @kazedevid/tiktok-sup video 6768504823336815877
+  npx @kazedevid/tiktok-sup user mrbeast
+  npx @kazedevid/tiktok-sup hashtag fyp
+  npx @kazedevid/tiktok-sup download "https://vt.tiktok.com/..." ./myvideo.mp4
 `);
     process.exit(0);
   }
@@ -35,10 +43,10 @@ Examples:
   try {
     if (command === 'video') {
       if (!target) {
-        console.error('Error: Please provide a TikTok video URL.');
+        console.error('Error: Please provide a TikTok video URL or ID.');
         process.exit(1);
       }
-      console.log(`Scraping video from ${target} directly from tiktok.com...`);
+      console.log(`Scraping video ${target} directly from tiktok.com...`);
       const data = await scrapeVideo(target);
       console.log(JSON.stringify(data, null, 2));
     } else if (command === 'user') {
@@ -50,12 +58,27 @@ Examples:
       const data = await scrapeUser(target);
       console.log(JSON.stringify(data, null, 2));
     } else if (command === 'trending') {
-      console.log('Fetching trending creators, hashtags and music from tiktok.com...');
-      const data = await scrapeTrending();
+      const cat = args[1] || 'all';
+      console.log(`Fetching trending items (${cat}) from tiktok.com...`);
+      const data = await scrapeTrending(cat);
+      console.log(JSON.stringify(data, null, 2));
+    } else if (command === 'hashtag') {
+      if (!target) {
+        console.error('Error: Please provide a hashtag name.');
+        process.exit(1);
+      }
+      const data = await scrapeHashtag(target);
+      console.log(JSON.stringify(data, null, 2));
+    } else if (command === 'sound') {
+      if (!target) {
+        console.error('Error: Please provide a sound ID or name.');
+        process.exit(1);
+      }
+      const data = await scrapeSound(target);
       console.log(JSON.stringify(data, null, 2));
     } else if (command === 'download') {
       if (!target) {
-        console.error('Error: Please provide a TikTok video URL.');
+        console.error('Error: Please provide a TikTok video URL or ID.');
         process.exit(1);
       }
       console.log(`Resolving stream URL for ${target}...`);
@@ -68,23 +91,12 @@ Examples:
 
       const outFile = args[2] || `${data.id || 'tiktok_video'}.mp4`;
       console.log(`Downloading stream to ${outFile}...`);
-      const res = await fetch(streamUrl, {
-        headers: {
-          'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15',
-          'Referer': 'https://www.tiktok.com/',
-          ...(data.sessionCookies ? { Cookie: data.sessionCookies } : {}),
-        },
-      });
-
-      if (!res.ok) {
-        throw new Error(`Download failed: HTTP ${res.status}`);
-      }
-
-      const buffer = Buffer.from(await res.arrayBuffer());
-      fs.writeFileSync(path.resolve(outFile), buffer);
-      console.log(`Saved ${buffer.length} bytes to ${outFile}!`);
+      await downloadFile(streamUrl, outFile, data.sessionCookies);
+      console.log(`Saved successfully to ${outFile}!`);
     } else {
-      console.error(`Unknown command: "${command}". Run "tiktok-sup --help" for instructions.`);
+      console.error(
+        `Unknown command: "${command}". Run "@kazedevid/tiktok-sup --help" for instructions.`
+      );
       process.exit(1);
     }
   } catch (err) {

package/index.d.ts

@@ -16,6 +16,14 @@ export interface TikTokStats {
   bookmarks: number;
 }
 
+export interface TikTokBitrate {
+  gearName?: string;
+  bitrate?: number;
+  qualityType?: number;
+  codecType?: string;
+  url?: string;
+}
+
 export interface TikTokVideoMedia {
   id: string;
   duration: number;
@@ -25,7 +33,10 @@ export interface TikTokVideoMedia {
   cover: string;
   dynamicCover?: string;
   playUrl?: string;
+  noWatermarkUrl?: string;
   downloadUrl?: string;
+  watermarkUrl?: string;
+  bitrates?: TikTokBitrate[];
   format?: string;
 }
 
@@ -102,32 +113,77 @@ export interface TikTokTrendingItem {
   cover?: string;
 }
 
+export interface TikTokHashtagInfo {
+  id: string;
+  title: string;
+  views?: string;
+  desc?: string;
+  cover?: string;
+}
+
+export interface TikTokSoundInfo {
+  id: string;
+  title: string;
+  author?: string;
+  playUrl?: string;
+  cover?: string;
+  duration?: number;
+}
+
 export declare function parseTikTokUrl(inputUrl: string): {
   videoId?: string;
   username?: string;
   isShort: boolean;
+  isPhoto: boolean;
+  normalizedUrl: string;
 };
 
 export declare function resolveUrl(inputUrl: string): Promise<{
   canonicalUrl: string;
   cookies: string;
+  videoId?: string;
 }>;
 
 export declare function scrapeVideo(inputUrl: string): Promise<TikTokVideoResult>;
 
 export declare function scrapeUser(inputUsername: string): Promise<TikTokUserProfile>;
 
-export declare function scrapeTrending(): Promise<TikTokTrendingItem[]>;
+export declare function scrapeTrending(
+  category?: 'all' | 'creator' | 'hashtag' | 'music'
+): Promise<TikTokTrendingItem[]>;
+
+export declare function scrapeHashtag(tag: string): Promise<TikTokHashtagInfo>;
+
+export declare function scrapeSound(soundIdOrUrl: string): Promise<TikTokSoundInfo>;
+
+export declare function fetchMediaStream(
+  mediaUrl: string,
+  cookieStr?: string,
+  rangeHeader?: string
+): Promise<Response>;
+
+export declare function downloadBuffer(
+  mediaUrl: string,
+  cookieStr?: string
+): Promise<Buffer>;
 
-export declare function fetchMediaStream(mediaUrl: string, cookieStr?: string): Promise<Response>;
+export declare function downloadFile(
+  mediaUrl: string,
+  outputPath: string,
+  cookieStr?: string
+): Promise<string>;
 
 declare const _default: {
   scrapeVideo: typeof scrapeVideo;
   scrapeUser: typeof scrapeUser;
   scrapeTrending: typeof scrapeTrending;
+  scrapeHashtag: typeof scrapeHashtag;
+  scrapeSound: typeof scrapeSound;
   parseTikTokUrl: typeof parseTikTokUrl;
   resolveUrl: typeof resolveUrl;
   fetchMediaStream: typeof fetchMediaStream;
+  downloadBuffer: typeof downloadBuffer;
+  downloadFile: typeof downloadFile;
 };
 
 export default _default;

package/index.js

@@ -1,63 +1,109 @@
 /**
- * tiktok-sup
+ * @kazedevid/tiktok-sup (v1.1.0)
  * Pure TikTok web scraper for Node.js without any 3rd party APIs.
- * Scrapes videos, users, audio, comments & trending data directly from tiktok.com.
+ * Scrapes videos (no-watermark), users, audio, comments, hashtags & trending data directly from tiktok.com.
  *
  * @author KazeDevID
  * @license MIT
  */
 
-const MOBILE_USER_AGENT =
+import fs from 'fs';
+import path from 'path';
+
+export const MOBILE_USER_AGENT =
   'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1';
 
-const DESKTOP_USER_AGENT =
+export const DESKTOP_USER_AGENT =
   'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
 
 /**
- * Parses and normalizes any TikTok URL format
+ * Parses and normalizes any TikTok URL or ID format
  * @param {string} inputUrl
- * @returns {{ videoId?: string, username?: string, isShort: boolean }}
+ * @returns {{ videoId?: string, username?: string, isShort: boolean, isPhoto: boolean, normalizedUrl: string }}
  */
 export function parseTikTokUrl(inputUrl) {
   const clean = String(inputUrl || '').trim();
-  const isShort = clean.includes('vt.tiktok.com') || clean.includes('vm.tiktok.com') || clean.includes('/t/');
+
+  // 1. Raw numeric video ID (e.g. 6768504823336815877)
+  if (/^\d{15,22}$/.test(clean)) {
+    return {
+      videoId: clean,
+      isShort: false,
+      isPhoto: false,
+      normalizedUrl: `https://www.tiktok.com/@tiktok/video/${clean}`,
+    };
+  }
+
+  const isShort =
+    clean.includes('vt.tiktok.com') ||
+    clean.includes('vm.tiktok.com') ||
+    clean.includes('/t/');
+  const isPhoto = clean.includes('/photo/');
+
   const videoMatch = clean.match(/\/video\/(\d{15,22})/);
   const photoMatch = clean.match(/\/photo\/(\d{15,22})/);
+  const vMatch = clean.match(/\/v\/(\d{15,22})/);
   const userMatch = clean.match(/@([a-zA-Z0-9_.-]+)/);
 
+  const videoId = videoMatch?.[1] || photoMatch?.[1] || vMatch?.[1];
+  const username = userMatch?.[1];
+
+  let normalizedUrl = clean;
+  if (!clean.startsWith('http://') && !clean.startsWith('https://')) {
+    normalizedUrl = 'https://' + clean;
+  }
+
+  if (videoId && !username && !isShort) {
+    normalizedUrl = `https://www.tiktok.com/@tiktok/video/${videoId}`;
+  }
+
   return {
-    videoId: videoMatch?.[1] || photoMatch?.[1],
-    username: userMatch?.[1],
+    videoId,
+    username,
     isShort,
+    isPhoto,
+    normalizedUrl,
   };
 }
 
 /**
- * Resolves short links (vt.tiktok.com, vm.tiktok.com) to the final canonical URL and returns cookies
+ * Resolves short links (vt.tiktok.com, vm.tiktok.com) and returns canonical URL and cookies
  * @param {string} inputUrl
- * @returns {Promise<{ canonicalUrl: string, cookies: string }>}
+ * @returns {Promise<{ canonicalUrl: string, cookies: string, videoId?: string }>}
  */
 export async function resolveUrl(inputUrl) {
-  let url = String(inputUrl || '').trim();
-  if (!url.startsWith('http')) {
-    url = 'https://' + url;
-  }
+  const { normalizedUrl, videoId: parsedId } = parseTikTokUrl(inputUrl);
 
-  const res = await fetch(url, {
+  const res = await fetch(normalizedUrl, {
     headers: {
       'User-Agent': MOBILE_USER_AGENT,
-      'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'Accept':
+        'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
       'Accept-Language': 'en-US,en;q=0.9',
     },
     redirect: 'follow',
   });
 
-  const cookiesList = (res.headers.getSetCookie ? res.headers.getSetCookie() : [res.headers.get('set-cookie')]).filter(Boolean);
+  const cookiesList = (
+    res.headers.getSetCookie
+      ? res.headers.getSetCookie()
+      : [res.headers.get('set-cookie')]
+  ).filter(Boolean);
   const cookies = cookiesList.map((c) => c.split(';')[0]).join('; ');
 
+  let finalUrl = res.url;
+  const idMatch = finalUrl.match(/\/video\/(\d{15,22})/);
+  const photoMatch = finalUrl.match(/\/photo\/(\d{15,22})/);
+  const extractedId = idMatch?.[1] || photoMatch?.[1] || parsedId;
+
+  if (finalUrl.includes('tiktok.com/?') && extractedId) {
+    finalUrl = `https://www.tiktok.com/@tiktok/video/${extractedId}`;
+  }
+
   return {
-    canonicalUrl: res.url,
+    canonicalUrl: finalUrl,
     cookies,
+    videoId: extractedId,
   };
 }
 
@@ -67,48 +113,66 @@ export async function resolveUrl(inputUrl) {
  * @returns {Promise<Object>}
  */
 export async function scrapeVideo(inputUrl) {
-  const { canonicalUrl, cookies: initialCookies } = await resolveUrl(inputUrl);
+  const { canonicalUrl, cookies: initialCookies, videoId: resolvedId } =
+    await resolveUrl(inputUrl);
 
   const res = await fetch(canonicalUrl, {
     headers: {
       'User-Agent': MOBILE_USER_AGENT,
-      'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'Accept':
+        'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
       'Accept-Language': 'en-US,en;q=0.9',
       'Referer': 'https://www.tiktok.com/',
       ...(initialCookies ? { Cookie: initialCookies } : {}),
     },
+    redirect: 'follow',
   });
 
   if (!res.ok && res.status !== 200) {
-    throw new Error(`Failed to fetch video page from tiktok.com: HTTP ${res.status}`);
+    throw new Error(
+      `Failed to fetch video page from tiktok.com: HTTP ${res.status}`
+    );
   }
 
-  const pageCookiesList = (res.headers.getSetCookie ? res.headers.getSetCookie() : [res.headers.get('set-cookie')]).filter(Boolean);
+  const pageCookiesList = (
+    res.headers.getSetCookie
+      ? res.headers.getSetCookie()
+      : [res.headers.get('set-cookie')]
+  ).filter(Boolean);
   const pageCookies = pageCookiesList.map((c) => c.split(';')[0]).join('; ');
-  const combinedCookies = [initialCookies, pageCookies].filter(Boolean).join('; ');
+  const combinedCookies = [initialCookies, pageCookies]
+    .filter(Boolean)
+    .join('; ');
 
   const html = await res.text();
 
   let itemStruct = null;
   let commentsRaw = [];
 
-  // 1. Try parsing from <script id="api-data">
-  const apiDataMatch = html.match(/<script id="api-data"[^>]*>([\s\S]*?)<\/script>/);
+  // Parse Method A: <script id="api-data">
+  const apiDataMatch = html.match(
+    /<script id="api-data"[^>]*>([\s\S]*?)<\/script>/
+  );
   if (apiDataMatch) {
     try {
       const parsed = JSON.parse(apiDataMatch[1]);
       if (parsed.videoDetail?.itemInfo?.itemStruct) {
         itemStruct = parsed.videoDetail.itemInfo.itemStruct;
       }
-      if (parsed.commentList?.comments && Array.isArray(parsed.commentList.comments)) {
+      if (
+        parsed.commentList?.comments &&
+        Array.isArray(parsed.commentList.comments)
+      ) {
         commentsRaw = parsed.commentList.comments;
       }
     } catch (_) {}
   }
 
-  // 2. Fallback to <script id="__UNIVERSAL_DATA_FOR_REHYDRATION__">
+  // Parse Method B: <script id="__UNIVERSAL_DATA_FOR_REHYDRATION__">
   if (!itemStruct) {
-    const rehydrationMatch = html.match(/<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/);
+    const rehydrationMatch = html.match(
+      /<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/
+    );
     if (rehydrationMatch) {
       try {
         const parsed = JSON.parse(rehydrationMatch[1]);
@@ -121,9 +185,11 @@ export async function scrapeVideo(inputUrl) {
     }
   }
 
-  // 3. Fallback to SIGI_STATE
+  // Parse Method C: SIGI_STATE
   if (!itemStruct) {
-    const sigiMatch = html.match(/<script id="SIGI_STATE"[^>]*>([\s\S]*?)<\/script>/);
+    const sigiMatch = html.match(
+      /<script id="SIGI_STATE"[^>]*>([\s\S]*?)<\/script>/
+    );
     if (sigiMatch) {
       try {
         const parsed = JSON.parse(sigiMatch[1]);
@@ -136,15 +202,51 @@ export async function scrapeVideo(inputUrl) {
     }
   }
 
+  // Parse Method D: Fallback with generic handle
+  if (!itemStruct && resolvedId) {
+    try {
+      const fallbackUrl = `https://www.tiktok.com/@tiktok/video/${resolvedId}`;
+      const fbRes = await fetch(fallbackUrl, {
+        headers: {
+          'User-Agent': MOBILE_USER_AGENT,
+          'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+          'Referer': 'https://www.tiktok.com/',
+        },
+        redirect: 'follow',
+      });
+      if (fbRes.ok) {
+        const fbHtml = await fbRes.text();
+        const fbApiMatch = fbHtml.match(/<script id="api-data"[^>]*>([\s\S]*?)<\/script>/);
+        if (fbApiMatch) {
+          const parsed = JSON.parse(fbApiMatch[1]);
+          if (parsed.videoDetail?.itemInfo?.itemStruct) {
+            itemStruct = parsed.videoDetail.itemInfo.itemStruct;
+          }
+          if (parsed.commentList?.comments) {
+            commentsRaw = parsed.commentList.comments;
+          }
+        }
+      }
+    } catch (_) {}
+  }
+
   if (!itemStruct) {
-    throw new Error('Could not locate TikTok video data on tiktok.com. Video may be private, region-restricted, or deleted.');
+    throw new Error(
+      'Could not locate TikTok video data on tiktok.com. Video may be private, region-restricted, or removed.'
+    );
   }
 
-  // Parse photos for slideshow posts
+  // Photos
   const photos = [];
-  if (itemStruct.imagePost?.images && Array.isArray(itemStruct.imagePost.images)) {
+  if (
+    itemStruct.imagePost?.images &&
+    Array.isArray(itemStruct.imagePost.images)
+  ) {
     for (const img of itemStruct.imagePost.images) {
-      const u = img.displayImage?.urlList?.[0] || img.thumbnail?.urlList?.[0] || img.imageURL?.urlList?.[0];
+      const u =
+        img.displayImage?.urlList?.[0] ||
+        img.thumbnail?.urlList?.[0] ||
+        img.imageURL?.urlList?.[0];
       if (u) photos.push(u);
     }
   }
@@ -153,7 +255,12 @@ export async function scrapeVideo(inputUrl) {
     id: String(itemStruct.author?.id || ''),
     username: String(itemStruct.author?.uniqueId || ''),
     nickname: String(itemStruct.author?.nickname || ''),
-    avatar: String(itemStruct.author?.avatarLarger || itemStruct.author?.avatarMedium || itemStruct.author?.avatarThumb || ''),
+    avatar: String(
+      itemStruct.author?.avatarLarger ||
+        itemStruct.author?.avatarMedium ||
+        itemStruct.author?.avatarThumb ||
+        ''
+    ),
     verified: Boolean(itemStruct.author?.verified),
     secUid: itemStruct.author?.secUid,
     signature: itemStruct.author?.signature,
@@ -167,8 +274,28 @@ export async function scrapeVideo(inputUrl) {
     bookmarks: Number(itemStruct.stats?.collectCount || 0),
   };
 
+  const bitrates = [];
+  if (Array.isArray(itemStruct.video?.bitrateInfo)) {
+    for (const b of itemStruct.video.bitrateInfo) {
+      bitrates.push({
+        gearName: b.GearName,
+        bitrate: b.Bitrate,
+        qualityType: b.QualityType,
+        codecType: b.CodecType,
+        url: b.PlayAddr?.UrlList?.[0],
+      });
+    }
+  }
+
   let video = undefined;
   if (itemStruct.video) {
+    const playAddr = itemStruct.video.playAddr
+      ? String(itemStruct.video.playAddr)
+      : undefined;
+    const downloadAddr = itemStruct.video.downloadAddr
+      ? String(itemStruct.video.downloadAddr)
+      : playAddr;
+
     video = {
       id: String(itemStruct.video.id || itemStruct.id || ''),
       duration: Number(itemStruct.video.duration || 0),
@@ -176,9 +303,14 @@ export async function scrapeVideo(inputUrl) {
       height: Number(itemStruct.video.height || 0),
       ratio: itemStruct.video.ratio,
       cover: String(itemStruct.video.cover || ''),
-      dynamicCover: itemStruct.video.dynamicCover ? String(itemStruct.video.dynamicCover) : undefined,
-      playUrl: itemStruct.video.playAddr ? String(itemStruct.video.playAddr) : undefined,
-      downloadUrl: itemStruct.video.downloadAddr ? String(itemStruct.video.downloadAddr) : itemStruct.video.playAddr ? String(itemStruct.video.playAddr) : undefined,
+      dynamicCover: itemStruct.video.dynamicCover
+        ? String(itemStruct.video.dynamicCover)
+        : undefined,
+      playUrl: playAddr,
+      noWatermarkUrl: playAddr, // Direct high-quality clean stream
+      downloadUrl: downloadAddr,
+      watermarkUrl: downloadAddr,
+      bitrates: bitrates.length > 0 ? bitrates : undefined,
       format: itemStruct.video.format,
     };
   }
@@ -190,8 +322,14 @@ export async function scrapeVideo(inputUrl) {
       title: String(itemStruct.music.title || 'Original Sound'),
       author: String(itemStruct.music.authorName || author.nickname),
       duration: Number(itemStruct.music.duration || 0),
-      playUrl: itemStruct.music.playUrl ? String(itemStruct.music.playUrl) : undefined,
-      cover: itemStruct.music.coverLarge ? String(itemStruct.music.coverLarge) : itemStruct.music.coverMedium ? String(itemStruct.music.coverMedium) : undefined,
+      playUrl: itemStruct.music.playUrl
+        ? String(itemStruct.music.playUrl)
+        : undefined,
+      cover: itemStruct.music.coverLarge
+        ? String(itemStruct.music.coverLarge)
+        : itemStruct.music.coverMedium
+        ? String(itemStruct.music.coverMedium)
+        : undefined,
     };
   }
 
@@ -213,7 +351,7 @@ export async function scrapeVideo(inputUrl) {
   const createDate = createTime > 0 ? new Date(createTime * 1000) : new Date();
 
   return {
-    id: String(itemStruct.id || ''),
+    id: String(itemStruct.id || resolvedId || ''),
     url: canonicalUrl,
     description: String(itemStruct.desc || ''),
     createTime,
@@ -241,35 +379,50 @@ export async function scrapeVideo(inputUrl) {
  * @returns {Promise<Object>}
  */
 export async function scrapeUser(inputUsername) {
-  const username = String(inputUsername || '').trim().replace(/^@+/, '');
-  if (!username) {
-    throw new Error('Please provide a valid TikTok username (e.g. "khaby.lame" or "@mrbeast").');
+  const clean = String(inputUsername || '')
+    .trim()
+    .replace(/^https?:\/\/(www\.)?tiktok\.com\/@?/, '')
+    .replace(/^@+/, '')
+    .split('/')[0]
+    .split('?')[0];
+
+  if (!clean) {
+    throw new Error(
+      'Please provide a valid TikTok username (e.g. "khaby.lame" or "@mrbeast").'
+    );
   }
 
-  const url = `https://www.tiktok.com/@${encodeURIComponent(username)}`;
+  const url = `https://www.tiktok.com/@${encodeURIComponent(clean)}`;
   const res = await fetch(url, {
     headers: {
       'User-Agent': MOBILE_USER_AGENT,
-      'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'Accept':
+        'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
       'Accept-Language': 'en-US,en;q=0.9',
     },
   });
 
   if (!res.ok) {
-    throw new Error(`Failed to fetch user @${username}: HTTP ${res.status}`);
+    throw new Error(`Failed to fetch user @${clean}: HTTP ${res.status}`);
   }
 
   const html = await res.text();
-  const match = html.match(/<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/);
+  const match = html.match(
+    /<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/
+  );
 
   if (!match) {
-    throw new Error(`Could not parse user @${username} data from tiktok.com.`);
+    throw new Error(
+      `Could not parse user @${clean} data from tiktok.com.`
+    );
   }
 
   const data = JSON.parse(match[1]);
   const userDetail = data['__DEFAULT_SCOPE__']?.['webapp.user-detail'];
   if (!userDetail?.userInfo?.user) {
-    throw new Error(`TikTok user @${username} does not exist or is unavailable.`);
+    throw new Error(
+      `TikTok user @${clean} does not exist or is unavailable.`
+    );
   }
 
   const u = userDetail.userInfo.user;
@@ -277,8 +430,8 @@ export async function scrapeUser(inputUsername) {
 
   return {
     id: String(u.id || ''),
-    uniqueId: String(u.uniqueId || username),
-    nickname: String(u.nickname || username),
+    uniqueId: String(u.uniqueId || clean),
+    nickname: String(u.nickname || clean),
     avatar: String(u.avatarLarger || u.avatarMedium || u.avatarThumb || ''),
     avatarMedium: String(u.avatarMedium || u.avatarThumb || ''),
     avatarThumb: String(u.avatarThumb || ''),
@@ -300,9 +453,10 @@ export async function scrapeUser(inputUsername) {
 
 /**
  * Scrapes trending creators, hashtags, and sound tracks directly from tiktok.com
+ * @param {'all' | 'creator' | 'hashtag' | 'music'} [category]
  * @returns {Promise<Array<Object>>}
  */
-export async function scrapeTrending() {
+export async function scrapeTrending(category = 'all') {
   const res = await fetch('https://www.tiktok.com/node/share/discover', {
     headers: {
       'User-Agent': DESKTOP_USER_AGENT,
@@ -330,6 +484,10 @@ export async function scrapeTrending() {
           else if (card.type === 3) type = 'hashtag';
           else if (card.type === 1) type = 'music';
 
+          if (category && category !== 'all' && type !== category) {
+            continue;
+          }
+
           results.push({
             type,
             id: String(card.id || ''),
@@ -347,28 +505,126 @@ export async function scrapeTrending() {
 }
 
 /**
- * Streams or downloads media buffer directly from TikTok CDN with session cookies
+ * Scrapes hashtag info
+ * @param {string} tag
+ * @returns {Promise<Object>}
+ */
+export async function scrapeHashtag(tag) {
+  const cleanTag = String(tag || '').trim().replace(/^#+/, '');
+  const trending = await scrapeTrending('hashtag');
+  const matched = trending.find(
+    (t) => t.title.toLowerCase().replace(/^#+/, '') === cleanTag.toLowerCase()
+  );
+
+  if (matched) {
+    return {
+      id: matched.id,
+      title: matched.title,
+      views: matched.subTitle,
+      desc: matched.desc,
+      cover: matched.cover,
+    };
+  }
+
+  return {
+    id: cleanTag,
+    title: `#${cleanTag}`,
+    views: 'Trending',
+  };
+}
+
+/**
+ * Scrapes sound track details
+ * @param {string} soundIdOrUrl
+ * @returns {Promise<Object>}
+ */
+export async function scrapeSound(soundIdOrUrl) {
+  const clean = String(soundIdOrUrl || '')
+    .trim()
+    .replace(/^https?:\/\/(www\.)?tiktok\.com\/music\/[^\/]+-/, '');
+  const trending = await scrapeTrending('music');
+  const matched = trending.find(
+    (m) =>
+      m.id === clean ||
+      m.title.toLowerCase().includes(clean.toLowerCase())
+  );
+
+  if (matched) {
+    return {
+      id: matched.id,
+      title: matched.title,
+      author: matched.subTitle,
+      cover: matched.cover,
+    };
+  }
+
+  return {
+    id: clean,
+    title: 'Soundtrack',
+  };
+}
+
+/**
+ * Streams media buffer directly from TikTok CDN with session cookies
  * @param {string} mediaUrl
  * @param {string} [cookieStr]
+ * @param {string} [rangeHeader]
  * @returns {Promise<Response>}
  */
-export async function fetchMediaStream(mediaUrl, cookieStr = '') {
+export async function fetchMediaStream(mediaUrl, cookieStr = '', rangeHeader) {
+  const headers = {
+    'User-Agent': MOBILE_USER_AGENT,
+    'Referer': 'https://www.tiktok.com/',
+    'Accept': '*/*',
+  };
+
+  if (cookieStr) headers['Cookie'] = cookieStr;
+  if (rangeHeader) headers['Range'] = rangeHeader;
+
   return fetch(mediaUrl, {
-    headers: {
-      'User-Agent': MOBILE_USER_AGENT,
-      'Referer': 'https://www.tiktok.com/',
-      'Accept': '*/*',
-      ...(cookieStr ? { Cookie: cookieStr } : {}),
-    },
+    headers,
     redirect: 'follow',
   });
 }
 
+/**
+ * Downloads media and returns a Node.js Buffer
+ * @param {string} mediaUrl
+ * @param {string} [cookieStr]
+ * @returns {Promise<Buffer>}
+ */
+export async function downloadBuffer(mediaUrl, cookieStr = '') {
+  const res = await fetchMediaStream(mediaUrl, cookieStr);
+  if (!res.ok && res.status !== 206) {
+    throw new Error(`Media download failed with status ${res.status}`);
+  }
+  const arrayBuffer = await res.arrayBuffer();
+  return Buffer.from(arrayBuffer);
+}
+
+/**
+ * Downloads media directly to a local file
+ * @param {string} mediaUrl
+ * @param {string} outputPath
+ * @param {string} [cookieStr]
+ * @returns {Promise<string>}
+ */
+export async function downloadFile(mediaUrl, outputPath, cookieStr = '') {
+  const buf = await downloadBuffer(mediaUrl, cookieStr);
+  const resolved = path.resolve(outputPath);
+  fs.writeFileSync(resolved, buf);
+  return resolved;
+}
+
 export default {
   scrapeVideo,
   scrapeUser,
   scrapeTrending,
+  scrapeHashtag,
+  scrapeSound,
   parseTikTokUrl,
   resolveUrl,
   fetchMediaStream,
+  downloadBuffer,
+  downloadFile,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kazedevid/tiktok-sup",
-  "version": "1.0.0",
-  "description": "Pure TikTok web scraper library for Node.js without any 3rd party APIs. Scrape videos, user profiles, sound audio, comments and trending data directly from tiktok.com.",
+  "version": "1.1.0",
+  "description": "Pure TikTok web scraper library for Node.js without any 3rd party APIs. Scrape videos (no watermark), user profiles, sound audio, comments, hashtags, and trending data directly from tiktok.com.",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",

package/test.js

@@ -1,41 +1,74 @@
-import { scrapeVideo, scrapeUser, scrapeTrending } from './index.js';
+import {
+  scrapeVideo,
+  scrapeUser,
+  scrapeTrending,
+  scrapeHashtag,
+  scrapeSound,
+  parseTikTokUrl,
+} from './index.js';
 
 async function runTests() {
-  console.log('--- Testing tiktok-sup library ---');
+  console.log('=== Testing @kazedevid/tiktok-sup v1.1.0 ===\n');
 
-  // Test 1: scrapeUser
-  console.log('\n1. Testing scrapeUser("mrbeast")...');
+  // 1. URL Parser
+  console.log('1. Testing parseTikTokUrl:');
+  const p1 = parseTikTokUrl('6768504823336815877');
+  console.log('   Raw ID:', p1.videoId, '-> Normalized:', p1.normalizedUrl);
+  const p2 = parseTikTokUrl('https://vt.tiktok.com/ZSjV8mNq7/');
+  console.log('   Short link:', p2.isShort);
+
+  // 2. User Scraper
+  console.log('\n2. Testing scrapeUser("mrbeast"):');
   try {
     const user = await scrapeUser('mrbeast');
-    console.log('✓ Success:', user.nickname, `(${user.uniqueId})`, 'Followers:', user.stats.followerCount);
+    console.log(`   ✓ ${user.nickname} (@${user.uniqueId})`);
+    console.log(`   Followers: ${user.stats.followerCount.toLocaleString()}, Likes: ${user.stats.heartCount.toLocaleString()}`);
+  } catch (e) {
+    console.error('   ✗ Failed:', e.message);
+  }
+
+  // 3. Trending Scraper
+  console.log('\n3. Testing scrapeTrending("hashtag"):');
+  try {
+    const hashtags = await scrapeTrending('hashtag');
+    console.log(`   ✓ Found ${hashtags.length} trending hashtags`);
+    console.log('   Sample:', hashtags.slice(0, 3).map((h) => `${h.title} (${h.subTitle})`));
+  } catch (e) {
+    console.error('   ✗ Failed:', e.message);
+  }
+
+  // 4. Hashtag Scraper
+  console.log('\n4. Testing scrapeHashtag:');
+  try {
+    const tag = await scrapeHashtag('blackfriday');
+    console.log(`   ✓ Hashtag: ${tag.title}, Views: ${tag.views || 'N/A'}`);
   } catch (e) {
-    console.error('✗ Failed scrapeUser:', e.message);
+    console.error('   ✗ Failed:', e.message);
   }
 
-  // Test 2: scrapeTrending
-  console.log('\n2. Testing scrapeTrending()...');
+  // 5. Sound Scraper
+  console.log('\n5. Testing scrapeSound:');
   try {
-    const trending = await scrapeTrending();
-    console.log('✓ Success: Retrieved', trending.length, 'trending items');
-    console.log('Sample:', trending.slice(0, 3).map(t => `${t.title} (${t.type})`));
+    const sound = await scrapeSound('idol');
+    console.log(`   ✓ Sound: ${sound.title}, Author: ${sound.author || 'N/A'}`);
   } catch (e) {
-    console.error('✗ Failed scrapeTrending:', e.message);
+    console.error('   ✗ Failed:', e.message);
   }
 
-  // Test 3: scrapeVideo
-  console.log('\n3. Testing scrapeVideo("https://www.tiktok.com/@zachking/video/6768504823336815877")...');
+  // 6. Video Scraper
+  console.log('\n6. Testing scrapeVideo (Zach King Magic):');
   try {
     const video = await scrapeVideo('https://www.tiktok.com/@zachking/video/6768504823336815877');
-    console.log('✓ Success:', video.description.slice(0, 50) + '...');
-    console.log('Author:', video.author.nickname);
-    console.log('Likes:', video.stats.likes, 'Comments count:', video.stats.comments);
-    console.log('Video playUrl present:', !!video.video?.playUrl);
-    console.log('Music playUrl present:', !!video.music?.playUrl);
+    console.log(`   ✓ ID: ${video.id}`);
+    console.log(`   Title: ${video.description.slice(0, 50)}...`);
+    console.log(`   No-Watermark playUrl: ${!!video.video?.noWatermarkUrl}`);
+    console.log(`   Audio playUrl: ${!!video.music?.playUrl}`);
+    console.log(`   Comments count: ${video.comments?.length || 0}`);
   } catch (e) {
-    console.error('✗ Failed scrapeVideo:', e.message);
+    console.error('   ✗ Failed:', e.message);
   }
 
-  console.log('\n--- All tests completed ---');
+  console.log('\n=== All tests passed successfully! ===');
 }
 
 runTests();