shadowx-tiksr 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# shadowx-tiksr
+
+🎵 TikTok video search & download module by Mueid Mursalin Rifat
+
+---
+
+📦 Installation
+
+```bash
+npm install shadowx-tiksr
+```
+
+Requires Node.js 18+ (recommended) or 16+.
+
+---
+
+🚀 Quick Start
+
+```javascript
+const TikSR = require('shadowx-tiksr');
+const tiktok = new TikSR();
+
+// Search videos
+async function searchTikTok() {
+  try {
+    const result = await tiktok.search('Goku');
+    
+    console.log('✅ Found!');
+    console.log('📹 Title:', result.video.title);
+    console.log('👤 Creator:', result.video.author.nickname);
+    console.log('❤️ Likes:', result.video.stats.likes);
+    console.log('📥 Download:', result.downloads.video);
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+searchTikTok();
+```
+
+---
+
+📥 Download Video Directly
+
+```javascript
+// Get first video download link
+const video = await tiktok.download('funny cats');
+console.log('Download URL:', video.download.video_url);
+```
+
+---
+
+📋 API Reference
+
+new TikSR(options)
+
+Option Type Default Description
+baseURL string 'https://shadowx-api.onrender.com/api' API endpoint
+timeout number 30000 Request timeout (ms)
+
+Methods
+
+Method Description Returns
+search(query) Search videos by keyword Promise<Object>
+download(query) Get first video download Promise<Object>
+extractVideoId(url) Extract ID from TikTok URL string\|null
+
+---
+
+📤 Response Format
+
+```javascript
+{
+  success: true,
+  query: "Goku",
+  
+  package: {
+    name: "shadowx-tiksr",
+    version: "1.0.0",
+    author: "Mueid Mursalin Rifat"
+  },
+  
+  video: {
+    title: "Son Goku Super Saiyan 5 THIS FORM IS INSANE 🔥",
+    region: "PK",
+    duration: 30,
+    play_url: "https://.../video.mp4",
+    music_url: "https://.../audio.mp3",
+    
+    stats: {
+      play_count: "56.6K",
+      likes: "2.9K", 
+      comments: "25",
+      shares: "154",
+      downloads: "25"
+    },
+    
+    author: {
+      nickname: "Skull Anime",
+      username: "skulanime",
+      profile_url: "https://www.tiktok.com/@skulanime"
+    }
+  },
+  
+  downloads: {
+    video: "https://.../video.mp4",
+    audio: "https://.../audio.mp3",
+    video_no_watermark: "https://.../video.mp4"
+  },
+  
+  metadata: {
+    region: "PK",
+    operator: "Mueid Mursalin Rifat",
+    powered_by: "CatX TikTok API",
+    timestamp: "2024-01-01T12:00:00.000Z"
+  }
+}
+```
+
+---
+
+📝 Examples
+
+Search with Different Queries
+
+```javascript
+const tiktok = new TikSR();
+
+const queries = ['dance', 'cooking', 'funny cats'];
+
+for (const query of queries) {
+  const result = await tiktok.search(query);
+  console.log(`${query}: ${result.video.title}`);
+}
+```
+
+Get Video Statistics
+
+```javascript
+const result = await tiktok.search('anime');
+
+console.log('📊 Statistics:');
+console.log(`👁️ Views: ${result.video.stats.play_count}`);
+console.log(`❤️ Likes: ${result.video.stats.likes}`);
+console.log(`💬 Comments: ${result.video.stats.comments}`);
+console.log(`↗️ Shares: ${result.video.stats.shares}`);
+```
+
+Extract Video ID from URL
+
+```javascript
+const url = 'https://www.tiktok.com/@user/video/123456789';
+const videoId = tiktok.extractVideoId(url);
+console.log(videoId); // '123456789'
+```
+
+Error Handling
+
+```javascript
+try {
+  const result = await tiktok.search('');
+} catch (error) {
+  console.log('Error Code:', error.code);
+  console.log('Message:', error.message);
+  console.log('Status:', error.statusCode);
+}
+```
+
+Common error codes:
+
+· INVALID_QUERY - Empty or invalid search
+· NOT_FOUND - No videos found
+· RATE_LIMITED - Too many requests
+· TIMEOUT - Request timed out
+· NETWORK_ERROR - Connection issues
+
+---
+
+⚙️ Configuration
+
+Environment Variables
+
+```bash
+TIKTOK_API_URL=https://shadowx-api.onrender.com/api
+TIKTOK_TIMEOUT=30000
+```
+
+Custom Configuration
+
+```javascript
+const tiktok = new TikSR({
+  baseURL: 'https://your-custom-api.com/api',
+  timeout: 60000 // 60 seconds
+});
+```
+
+---
+
+🔧 Requirements
+
+· Node.js: 16.x or higher (18+ recommended)
+· npm: 7.x or higher
+
+---
+
+
+---
+
+📄 License
+
+MIT © Mueid Mursalin Rifat
+
+---
+
+🙏 Credits
+
+· Author: Mueid Mursalin Rifat
+· API: ShadowX TikTokSr API
+· Powered by: ShadowX
+
+---
+
+🔗 Links
+
+· npm Package
+· GitHub Repository
+· Issue Tracker
+
+---
+
+
+---

package/index.js

@@ -0,0 +1,245 @@
+const axios = require('axios');
+
+class ShadowXTikSR {
+  constructor(options = {}) {
+    this.baseURL = options.baseURL || 'https://shadowx-api.onrender.com/api';
+    this.timeout = options.timeout || 30000;
+    this.userAgent = options.userAgent || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36';
+    
+    this.client = axios.create({
+      baseURL: this.baseURL,
+      timeout: this.timeout,
+      headers: {
+        'User-Agent': this.userAgent,
+        'Accept': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Get module metadata
+   */
+  static getMeta() {
+    return {
+      name: "shadowx-tiksr",
+      version: "1.0.0",
+      description: "TikTok search and download module",
+      author: "Mueid Mursalin Rifat",
+      license: "MIT",
+      supported: ["Video search", "Video download", "Metadata extraction"]
+    };
+  }
+
+  /**
+   * Search TikTok videos by query
+   * @param {string} query - Search term (e.g., "Goku", "funny cats", "dance")
+   * @returns {Promise<Object>} Search results with video details
+   */
+  async search(query) {
+    if (!query || typeof query !== 'string') {
+      throw new Error('Search query is required');
+    }
+
+    try {
+      console.log(`🔍 Searching TikTok for: "${query}"`);
+      
+      const response = await this.client.get('/tiksr', {
+        params: { query: encodeURIComponent(query) }
+      });
+
+      const data = response.data;
+
+      if (!data || !data.status) {
+        throw new Error(data?.message || 'Search failed');
+      }
+
+      return this._formatResponse(data, query);
+
+    } catch (error) {
+      throw this._handleError(error, { query });
+    }
+  }
+
+  /**
+   * Download TikTok video by search (returns first result)
+   * @param {string} query - Search term
+   * @returns {Promise<Object>} Video download info
+   */
+  async download(query) {
+    const result = await this.search(query);
+    
+    return {
+      success: true,
+      message: 'Video ready for download',
+      download: {
+        video_url: result.video.play_url,
+        audio_url: result.video.music_url,
+        filename: `${result.video.title?.substring(0, 50) || 'tiktok_video'}.mp4`,
+        size: 'Unknown', // API doesn't provide size
+        quality: 'HD'
+      },
+      ...result
+    };
+  }
+
+  /**
+   * Format API response
+   */
+  _formatResponse(data, query) {
+    // Format numbers with K/M/B suffixes
+    const formatNumber = (num) => {
+      if (!num && num !== 0) return 'N/A';
+      if (num >= 1000000) return (num / 1000000).toFixed(1) + 'M';
+      if (num >= 1000) return (num / 1000).toFixed(1) + 'K';
+      return num.toString();
+    };
+
+    return {
+      success: true,
+      query: query,
+      
+      // Package info
+      package: {
+        name: 'shadowx-tiksr',
+        version: '1.0.0',
+        author: 'Mueid Mursalin Rifat'
+      },
+
+      // Video details
+      video: {
+        title: data.title || 'No title',
+        region: data.region || 'Unknown',
+        duration: data.duration || 0,
+        play_url: data.play_url || null,
+        music_url: data.music_url || null,
+        
+        // Statistics
+        stats: {
+          play_count: formatNumber(data.stats?.play_count),
+          likes: formatNumber(data.stats?.likes),
+          comments: formatNumber(data.stats?.comments),
+          shares: formatNumber(data.stats?.shares),
+          downloads: formatNumber(data.stats?.downloads),
+          raw: data.stats // Original numbers
+        },
+        
+        // Author info
+        author: {
+          nickname: data.author?.nickname || 'Unknown',
+          username: data.author?.username || 'unknown',
+          profile_url: data.author?.username ? 
+            `https://www.tiktok.com/@${data.author.username}` : null
+        }
+      },
+
+      // Direct download links
+      downloads: {
+        video: data.play_url,
+        audio: data.music_url,
+        video_no_watermark: data.play_url, // API provides clean video
+        thumbnail: data.thumbnail || null
+      },
+
+      // Additional info
+      metadata: {
+        region: data.region,
+        operator: data.operator || 'Mueid Mursalin Rifat',
+        powered_by: data.powered_by || 'CatX TikTok API',
+        timestamp: new Date().toISOString()
+      },
+
+      // Raw data for reference
+      raw: data
+    };
+  }
+
+  /**
+   * Handle errors
+   */
+  _handleError(error, context = {}) {
+    let errorMessage = 'Failed to process TikTok request';
+    let statusCode = 500;
+    let errorCode = 'UNKNOWN_ERROR';
+
+    if (error.response) {
+      statusCode = error.response.status;
+      
+      switch (statusCode) {
+        case 400:
+          errorMessage = 'Invalid search query';
+          errorCode = 'INVALID_QUERY';
+          break;
+        case 404:
+          errorMessage = 'No videos found for this query';
+          errorCode = 'NOT_FOUND';
+          break;
+        case 429:
+          errorMessage = 'Rate limit exceeded. Try again later';
+          errorCode = 'RATE_LIMITED';
+          break;
+        case 500:
+        case 502:
+        case 503:
+          errorMessage = 'TikTok API service unavailable';
+          errorCode = 'SERVICE_UNAVAILABLE';
+          break;
+        default:
+          errorMessage = `API Error: ${error.response.data?.message || error.message}`;
+      }
+    } else if (error.code === 'ECONNABORTED') {
+      errorMessage = 'Request timeout';
+      errorCode = 'TIMEOUT';
+    } else if (error.code === 'ENOTFOUND') {
+      errorMessage = 'Network error - cannot connect to API';
+      errorCode = 'NETWORK_ERROR';
+    }
+
+    const formattedError = new Error(errorMessage);
+    formattedError.code = errorCode;
+    formattedError.statusCode = statusCode;
+    formattedError.context = context;
+    formattedError.timestamp = new Date().toISOString();
+    
+    return formattedError;
+  }
+
+  /**
+   * Get trending videos (if supported by API)
+   */
+  async trending() {
+    try {
+      const response = await this.client.get('/tiktok/trending');
+      return response.data;
+    } catch (error) {
+      throw this._handleError(error);
+    }
+  }
+
+  /**
+   * Extract video ID from TikTok URL
+   * @param {string} url - TikTok video URL
+   * @returns {string|null} Video ID
+   */
+  extractVideoId(url) {
+    if (!url) return null;
+    
+    const patterns = [
+      /tiktok\.com\/@[\w.-]+\/video\/(\d+)/i,
+      /tiktok\.com\/video\/(\d+)/i,
+      /vm\.tiktok\.com\/([\w]+)/i
+    ];
+    
+    for (const pattern of patterns) {
+      const match = url.match(pattern);
+      if (match) return match[1];
+    }
+    
+    return null;
+  }
+}
+
+// Export
+module.exports = ShadowXTikSR;
+module.exports.create = (options) => new ShadowXTikSR(options);
+module.exports.default = new ShadowXTikSR();
+module.exports.meta = ShadowXTikSR.getMeta();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "shadowx-tiksr",
+  "version": "1.0.0",
+  "description": "TikTok video search and download module - Search videos by query, get video details, download links, and metadata",
+  "main": "index.js",
+  "scripts": {
+    "test": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "tiktok",
+    "downloader",
+    "tiktok-downloader",
+    "tiktok-search",
+    "video-downloader",
+    "social-media",
+    "tiktok-api",
+    "shadowx",
+    "tiksr",
+    "tiktok-video",
+    "tiktok-no-watermark"
+  ],
+  "author": "Mueid Mursalin Rifat",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mueidmursalin/shadowx-tiksr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mueidmursalin/shadowx-tiksr/issues"
+  },
+  "homepage": "https://github.com/mueidmursalin/shadowx-tiksr#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}