@kazedevid/tiktok-sup 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KazeDevID
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# tiktok-sup 🚀
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **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.**
+
+[![npm version](https://img.shields.io/npm/v/tiktok-sup.svg?style=flat-square&color=cb0000)](https://www.npmjs.com/package/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)
+
+---
+
+## ✨ 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.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install tiktok-sup
+```
+
+or with yarn / pnpm:
+
+```bash
+yarn add tiktok-sup
+# or
+pnpm add tiktok-sup
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Scrape Video Metadata & Stream Links
+
+```javascript
+import { scrapeVideo } from 'tiktok-sup';
+
+// Works with any TikTok URL (desktop, mobile, or vt.tiktok.com short links)
+const video = await scrapeVideo('https://www.tiktok.com/@zachking/video/6768504823336815877');
+
+console.log('Title/Desc:', 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);
+```
+
+### 2. Scrape User Profile
+
+```javascript
+import { scrapeUser } from 'tiktok-sup';
+
+const profile = 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);
+```
+
+### 3. Explore Trending Creators & Hashtags
+
+```javascript
+import { scrapeTrending } from 'tiktok-sup';
+
+const trending = await scrapeTrending();
+trending.forEach(item => {
+  console.log(`[${item.type}] ${item.title} - ${item.subTitle || ''}`);
+});
+```
+
+### 4. Downloading or Streaming Videos Directly
+
+TikTok CDN requires session cookies and matching referer headers to stream:
+
+```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;
+
+// fetchMediaStream automatically attaches TikTok referer and session cookies
+const response = await fetchMediaStream(streamUrl, video.sessionCookies);
+const buffer = Buffer.from(await response.arrayBuffer());
+
+fs.writeFileSync('video.mp4', buffer);
+console.log('Downloaded video.mp4 successfully!');
+```
+
+---
+
+## 💻 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"
+
+# Scrape user profile
+npx tiktok-sup user khaby.lame
+
+# List trending topics
+npx tiktok-sup trending
+
+# Download video MP4 directly
+npx tiktok-sup download "https://vt.tiktok.com/..." output.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.
+
+---
+
+## 📄 License
+
+MIT © [KazeDevID](https://github.com/KazeDevID)

package/bin/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * tiktok-sup CLI
+ * 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';
+
+const args = process.argv.slice(2);
+const command = args[0];
+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)
+
+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
+
+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
+`);
+    process.exit(0);
+  }
+
+  try {
+    if (command === 'video') {
+      if (!target) {
+        console.error('Error: Please provide a TikTok video URL.');
+        process.exit(1);
+      }
+      console.log(`Scraping video from ${target} directly from tiktok.com...`);
+      const data = await scrapeVideo(target);
+      console.log(JSON.stringify(data, null, 2));
+    } else if (command === 'user') {
+      if (!target) {
+        console.error('Error: Please provide a TikTok username.');
+        process.exit(1);
+      }
+      console.log(`Scraping profile @${target} directly from tiktok.com...`);
+      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();
+      console.log(JSON.stringify(data, null, 2));
+    } else if (command === 'download') {
+      if (!target) {
+        console.error('Error: Please provide a TikTok video URL.');
+        process.exit(1);
+      }
+      console.log(`Resolving stream URL for ${target}...`);
+      const data = await scrapeVideo(target);
+      const streamUrl = data.video?.downloadUrl || data.video?.playUrl;
+      if (!streamUrl) {
+        console.error('No video stream URL found for this post.');
+        process.exit(1);
+      }
+
+      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}!`);
+    } else {
+      console.error(`Unknown command: "${command}". Run "tiktok-sup --help" for instructions.`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/index.d.ts

@@ -0,0 +1,133 @@
+export interface TikTokAuthor {
+  id: string;
+  username: string;
+  nickname: string;
+  avatar: string;
+  verified: boolean;
+  secUid?: string;
+  signature?: string;
+}
+
+export interface TikTokStats {
+  views: number;
+  likes: number;
+  comments: number;
+  shares: number;
+  bookmarks: number;
+}
+
+export interface TikTokVideoMedia {
+  id: string;
+  duration: number;
+  width: number;
+  height: number;
+  ratio?: string;
+  cover: string;
+  dynamicCover?: string;
+  playUrl?: string;
+  downloadUrl?: string;
+  format?: string;
+}
+
+export interface TikTokMusic {
+  id: string;
+  title: string;
+  author: string;
+  duration: number;
+  playUrl?: string;
+  cover?: string;
+}
+
+export interface TikTokComment {
+  cid: string;
+  text: string;
+  createTime: number;
+  diggCount: number;
+  replyCount: number;
+  user: {
+    id: string;
+    username: string;
+    nickname: string;
+    avatar: string;
+  };
+}
+
+export interface TikTokVideoResult {
+  id: string;
+  url: string;
+  description: string;
+  createTime: number;
+  createTimeFormatted: string;
+  author: TikTokAuthor;
+  stats: TikTokStats;
+  video?: TikTokVideoMedia;
+  music?: TikTokMusic;
+  isPhoto: boolean;
+  photos?: string[];
+  comments?: TikTokComment[];
+  sessionCookies?: string;
+}
+
+export interface TikTokUserProfile {
+  id: string;
+  uniqueId: string;
+  nickname: string;
+  avatar: string;
+  avatarMedium: string;
+  avatarThumb: string;
+  signature: string;
+  bioLink?: { link: string; risk: number };
+  verified: boolean;
+  secUid: string;
+  privateAccount: boolean;
+  stats: {
+    followerCount: number;
+    followingCount: number;
+    heartCount: number;
+    videoCount: number;
+    friendCount: number;
+  };
+  shareMeta?: {
+    title: string;
+    desc: string;
+  };
+}
+
+export interface TikTokTrendingItem {
+  type: 'creator' | 'hashtag' | 'music' | 'unknown';
+  id: string;
+  title: string;
+  subTitle?: string;
+  desc?: string;
+  cover?: string;
+}
+
+export declare function parseTikTokUrl(inputUrl: string): {
+  videoId?: string;
+  username?: string;
+  isShort: boolean;
+};
+
+export declare function resolveUrl(inputUrl: string): Promise<{
+  canonicalUrl: string;
+  cookies: 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 fetchMediaStream(mediaUrl: string, cookieStr?: string): Promise<Response>;
+
+declare const _default: {
+  scrapeVideo: typeof scrapeVideo;
+  scrapeUser: typeof scrapeUser;
+  scrapeTrending: typeof scrapeTrending;
+  parseTikTokUrl: typeof parseTikTokUrl;
+  resolveUrl: typeof resolveUrl;
+  fetchMediaStream: typeof fetchMediaStream;
+};
+
+export default _default;

package/index.js

@@ -0,0 +1,374 @@
+/**
+ * tiktok-sup
+ * Pure TikTok web scraper for Node.js without any 3rd party APIs.
+ * Scrapes videos, users, audio, comments & trending data directly from tiktok.com.
+ *
+ * @author KazeDevID
+ * @license MIT
+ */
+
+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 =
+  '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
+ * @param {string} inputUrl
+ * @returns {{ videoId?: string, username?: string, isShort: boolean }}
+ */
+export function parseTikTokUrl(inputUrl) {
+  const clean = String(inputUrl || '').trim();
+  const isShort = clean.includes('vt.tiktok.com') || clean.includes('vm.tiktok.com') || clean.includes('/t/');
+  const videoMatch = clean.match(/\/video\/(\d{15,22})/);
+  const photoMatch = clean.match(/\/photo\/(\d{15,22})/);
+  const userMatch = clean.match(/@([a-zA-Z0-9_.-]+)/);
+
+  return {
+    videoId: videoMatch?.[1] || photoMatch?.[1],
+    username: userMatch?.[1],
+    isShort,
+  };
+}
+
+/**
+ * Resolves short links (vt.tiktok.com, vm.tiktok.com) to the final canonical URL and returns cookies
+ * @param {string} inputUrl
+ * @returns {Promise<{ canonicalUrl: string, cookies: string }>}
+ */
+export async function resolveUrl(inputUrl) {
+  let url = String(inputUrl || '').trim();
+  if (!url.startsWith('http')) {
+    url = 'https://' + url;
+  }
+
+  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-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 cookies = cookiesList.map((c) => c.split(';')[0]).join('; ');
+
+  return {
+    canonicalUrl: res.url,
+    cookies,
+  };
+}
+
+/**
+ * Scrapes a TikTok video or photo post directly from tiktok.com
+ * @param {string} inputUrl
+ * @returns {Promise<Object>}
+ */
+export async function scrapeVideo(inputUrl) {
+  const { canonicalUrl, cookies: initialCookies } = 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-Language': 'en-US,en;q=0.9',
+      'Referer': 'https://www.tiktok.com/',
+      ...(initialCookies ? { Cookie: initialCookies } : {}),
+    },
+  });
+
+  if (!res.ok && res.status !== 200) {
+    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 pageCookies = pageCookiesList.map((c) => c.split(';')[0]).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>/);
+  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)) {
+        commentsRaw = parsed.commentList.comments;
+      }
+    } catch (_) {}
+  }
+
+  // 2. Fallback to <script id="__UNIVERSAL_DATA_FOR_REHYDRATION__">
+  if (!itemStruct) {
+    const rehydrationMatch = html.match(/<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/);
+    if (rehydrationMatch) {
+      try {
+        const parsed = JSON.parse(rehydrationMatch[1]);
+        const scope = parsed['__DEFAULT_SCOPE__'] || {};
+        const videoDetail = scope['webapp.video-detail'];
+        if (videoDetail?.itemInfo?.itemStruct) {
+          itemStruct = videoDetail.itemInfo.itemStruct;
+        }
+      } catch (_) {}
+    }
+  }
+
+  // 3. Fallback to SIGI_STATE
+  if (!itemStruct) {
+    const sigiMatch = html.match(/<script id="SIGI_STATE"[^>]*>([\s\S]*?)<\/script>/);
+    if (sigiMatch) {
+      try {
+        const parsed = JSON.parse(sigiMatch[1]);
+        const items = parsed.ItemModule || {};
+        const firstKey = Object.keys(items)[0];
+        if (firstKey && items[firstKey]) {
+          itemStruct = items[firstKey];
+        }
+      } catch (_) {}
+    }
+  }
+
+  if (!itemStruct) {
+    throw new Error('Could not locate TikTok video data on tiktok.com. Video may be private, region-restricted, or deleted.');
+  }
+
+  // Parse photos for slideshow posts
+  const photos = [];
+  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];
+      if (u) photos.push(u);
+    }
+  }
+
+  const author = {
+    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 || ''),
+    verified: Boolean(itemStruct.author?.verified),
+    secUid: itemStruct.author?.secUid,
+    signature: itemStruct.author?.signature,
+  };
+
+  const stats = {
+    views: Number(itemStruct.stats?.playCount || 0),
+    likes: Number(itemStruct.stats?.diggCount || 0),
+    comments: Number(itemStruct.stats?.commentCount || 0),
+    shares: Number(itemStruct.stats?.shareCount || 0),
+    bookmarks: Number(itemStruct.stats?.collectCount || 0),
+  };
+
+  let video = undefined;
+  if (itemStruct.video) {
+    video = {
+      id: String(itemStruct.video.id || itemStruct.id || ''),
+      duration: Number(itemStruct.video.duration || 0),
+      width: Number(itemStruct.video.width || 0),
+      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,
+      format: itemStruct.video.format,
+    };
+  }
+
+  let music = undefined;
+  if (itemStruct.music) {
+    music = {
+      id: String(itemStruct.music.id || ''),
+      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,
+    };
+  }
+
+  const comments = commentsRaw.map((c) => ({
+    cid: String(c.cid || ''),
+    text: String(c.text || ''),
+    createTime: Number(c.create_time || 0),
+    diggCount: Number(c.digg_count || 0),
+    replyCount: Number(c.reply_comment_total || 0),
+    user: {
+      id: String(c.user?.uid || ''),
+      username: String(c.user?.unique_id || ''),
+      nickname: String(c.user?.nickname || ''),
+      avatar: String(c.user?.avatar_thumb?.url_list?.[0] || ''),
+    },
+  }));
+
+  const createTime = Number(itemStruct.createTime || 0);
+  const createDate = createTime > 0 ? new Date(createTime * 1000) : new Date();
+
+  return {
+    id: String(itemStruct.id || ''),
+    url: canonicalUrl,
+    description: String(itemStruct.desc || ''),
+    createTime,
+    createTimeFormatted: createDate.toLocaleString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    }),
+    author,
+    stats,
+    video,
+    music,
+    isPhoto: photos.length > 0,
+    photos: photos.length > 0 ? photos : undefined,
+    comments: comments.length > 0 ? comments : undefined,
+    sessionCookies: combinedCookies,
+  };
+}
+
+/**
+ * Scrapes a TikTok user profile directly from tiktok.com
+ * @param {string} inputUsername
+ * @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 url = `https://www.tiktok.com/@${encodeURIComponent(username)}`;
+  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-Language': 'en-US,en;q=0.9',
+    },
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch user @${username}: HTTP ${res.status}`);
+  }
+
+  const html = await res.text();
+  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.`);
+  }
+
+  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.`);
+  }
+
+  const u = userDetail.userInfo.user;
+  const s = userDetail.userInfo.stats || {};
+
+  return {
+    id: String(u.id || ''),
+    uniqueId: String(u.uniqueId || username),
+    nickname: String(u.nickname || username),
+    avatar: String(u.avatarLarger || u.avatarMedium || u.avatarThumb || ''),
+    avatarMedium: String(u.avatarMedium || u.avatarThumb || ''),
+    avatarThumb: String(u.avatarThumb || ''),
+    signature: String(u.signature || ''),
+    bioLink: u.bioLink,
+    verified: Boolean(u.verified),
+    secUid: String(u.secUid || ''),
+    privateAccount: Boolean(u.privateAccount),
+    stats: {
+      followerCount: Number(s.followerCount || 0),
+      followingCount: Number(s.followingCount || 0),
+      heartCount: Number(s.heartCount || s.heart || 0),
+      videoCount: Number(s.videoCount || 0),
+      friendCount: Number(s.friendCount || 0),
+    },
+    shareMeta: userDetail.shareMeta,
+  };
+}
+
+/**
+ * Scrapes trending creators, hashtags, and sound tracks directly from tiktok.com
+ * @returns {Promise<Array<Object>>}
+ */
+export async function scrapeTrending() {
+  const res = await fetch('https://www.tiktok.com/node/share/discover', {
+    headers: {
+      'User-Agent': DESKTOP_USER_AGENT,
+      'Accept': 'application/json, text/plain, */*',
+      'Referer': 'https://www.tiktok.com/',
+    },
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch trending discovery data: HTTP ${res.status}`);
+  }
+
+  const json = await res.json();
+  const results = [];
+
+  if (Array.isArray(json.body)) {
+    for (const group of json.body) {
+      if (Array.isArray(group.exploreList)) {
+        for (const item of group.exploreList) {
+          const card = item.cardItem;
+          if (!card) continue;
+
+          let type = 'unknown';
+          if (card.type === 2) type = 'creator';
+          else if (card.type === 3) type = 'hashtag';
+          else if (card.type === 1) type = 'music';
+
+          results.push({
+            type,
+            id: String(card.id || ''),
+            title: String(card.title || ''),
+            subTitle: card.subTitle ? String(card.subTitle) : undefined,
+            desc: card.desc ? String(card.desc) : undefined,
+            cover: card.cover ? String(card.cover) : undefined,
+          });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Streams or downloads media buffer directly from TikTok CDN with session cookies
+ * @param {string} mediaUrl
+ * @param {string} [cookieStr]
+ * @returns {Promise<Response>}
+ */
+export async function fetchMediaStream(mediaUrl, cookieStr = '') {
+  return fetch(mediaUrl, {
+    headers: {
+      'User-Agent': MOBILE_USER_AGENT,
+      'Referer': 'https://www.tiktok.com/',
+      'Accept': '*/*',
+      ...(cookieStr ? { Cookie: cookieStr } : {}),
+    },
+    redirect: 'follow',
+  });
+}
+
+export default {
+  scrapeVideo,
+  scrapeUser,
+  scrapeTrending,
+  parseTikTokUrl,
+  resolveUrl,
+  fetchMediaStream,
+};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@kazedevid/tiktok-sup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "bin": {
+    "tiktok-sup": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "tiktok",
+    "tiktok-scraper",
+    "scraper",
+    "tiktok-downloader",
+    "tiktok-api",
+    "tiktok-web",
+    "no-watermark",
+    "video-downloader",
+    "kazedevid"
+  ],
+  "author": "KazeDevID",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KazeDevID/tiktok-sup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KazeDevID/tiktok-sup/issues"
+  },
+  "homepage": "https://github.com/KazeDevID/tiktok-sup#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }

package/test.js

@@ -0,0 +1,41 @@
+import { scrapeVideo, scrapeUser, scrapeTrending } from './index.js';
+
+async function runTests() {
+  console.log('--- Testing tiktok-sup library ---');
+
+  // Test 1: scrapeUser
+  console.log('\n1. Testing scrapeUser("mrbeast")...');
+  try {
+    const user = await scrapeUser('mrbeast');
+    console.log('✓ Success:', user.nickname, `(${user.uniqueId})`, 'Followers:', user.stats.followerCount);
+  } catch (e) {
+    console.error('✗ Failed scrapeUser:', e.message);
+  }
+
+  // Test 2: scrapeTrending
+  console.log('\n2. Testing scrapeTrending()...');
+  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})`));
+  } catch (e) {
+    console.error('✗ Failed scrapeTrending:', e.message);
+  }
+
+  // Test 3: scrapeVideo
+  console.log('\n3. Testing scrapeVideo("https://www.tiktok.com/@zachking/video/6768504823336815877")...');
+  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);
+  } catch (e) {
+    console.error('✗ Failed scrapeVideo:', e.message);
+  }
+
+  console.log('\n--- All tests completed ---');
+}
+
+runTests();