@sn5u/flixhq-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 staticsenju
+
+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

@@ -0,0 +1,203 @@
+# FlixHQ API
+
+A specialized Node.js library that provides an API for obtaining movie and TV show information, including metadata, seasons, episodes, and streaming sources from FlixHQ.
+
+## Features
+
+- **Home Data**: Fetch trending movies, TV shows, and latest releases.
+- **Search**: Advanced search functionality for movies and series.
+- **Filters**: Filter content by type (Movie/TV), Genre, Country, and Top IMDB.
+- **Details**: Scrape full metadata including plot, year, country, and cast.
+- **Episodes**: Retrieve full season and episode lists for TV series.
+- **Streaming**: Extract server lists and streaming sources (HLS/m3u8).
+
+## Installation
+
+```bash
+npm install flixhq-api
+
+```
+
+## Quick Start
+
+```javascript
+const FlixHQ = require('flixhq-api');
+
+const flixhq = new FlixHQ();
+
+(async () => {
+  const data = await flixhq.search("The Last of Us");
+  console.log(data);
+})();
+
+```
+
+## API Methods
+
+### Content Discovery
+
+#### `fetchHome()`
+
+Fetches data from the homepage, including Trending Movies, Trending TV, Latest Movies, and Latest TV.
+
+```javascript
+const home = await flixhq.fetchHome();
+console.log(home.trendingMovies);
+
+```
+
+#### `fetchMovies(page)`
+
+Fetches a list of movies.
+
+* `page` (number, optional): Default is 1.
+
+```javascript
+const movies = await flixhq.fetchMovies(1);
+
+```
+
+#### `fetchTVShows(page)`
+
+Fetches a list of TV shows.
+
+* `page` (number, optional): Default is 1.
+
+```javascript
+const tvShows = await flixhq.fetchTVShows(1);
+
+```
+
+#### `fetchTopIMDB(type, page)`
+
+Fetches content sorted by IMDB rating.
+
+* `type` (string, optional): 'all', 'movie', or 'tv'. Default 'all'.
+* `page` (number, optional): Default is 1.
+
+```javascript
+const topRated = await flixhq.fetchTopIMDB('movie', 1);
+
+```
+
+### Search & Filters
+
+#### `search(query)`
+
+Search for movies or TV shows by title.
+
+```javascript
+const results = await flixhq.search("Breaking Bad");
+// Returns: [{ id: 'breaking-bad-12345', title: 'Breaking Bad', ... }]
+
+```
+
+#### `fetchGenres()` & `fetchCountries()`
+
+Returns a list of available genres and countries for filtering.
+
+```javascript
+const genres = await flixhq.fetchGenres();
+const countries = await flixhq.fetchCountries();
+
+```
+
+#### `filter(type, value, page)`
+
+Filter content by specific criteria.
+
+* `type`: The filter category (e.g., 'genre', 'country').
+* `value`: The specific slug (e.g., 'action', 'us').
+
+```javascript
+const actionMovies = await flixhq.filter('genre', 'action', 1);
+
+```
+
+### Metadata & Media Info
+
+#### `getDetails(slug)`
+
+Get detailed information about a specific media item.
+
+* `slug`: The unique string ID (e.g., `movie/watch-avatar-12345`).
+
+```javascript
+const info = await flixhq.getDetails("movie/watch-avatar-12345");
+/* Returns:
+{
+  id: "12345",
+  title: "Avatar",
+  description: "...",
+  year: 2009,
+  released: "2009-12-18",
+  genres: ["Action", "Sci-Fi"]
+}
+*/
+
+```
+
+#### `getSeasons(slug)`
+
+Get available seasons for a TV show.
+
+```javascript
+const seasons = await flixhq.getSeasons("tv/watch-stranger-things-39444");
+
+```
+
+#### `getEpisodes(seasonId)`
+
+Get all episodes for a specific season ID.
+
+```javascript
+const episodes = await flixhq.getEpisodes("12345"); // seasonId returned from getSeasons
+
+```
+
+### Streaming
+
+#### `getServers(contentId, type)`
+
+Get available streaming servers for a movie or episode.
+
+* `contentId`: The ID of the movie or the specific episode ID.
+* `type`: 'movie' or 'tv'.
+
+```javascript
+// For a movie
+const servers = await flixhq.getServers("12345", "movie");
+
+// For an episode
+const servers = await flixhq.getServers("episode-id-67890", "tv");
+
+```
+
+#### `fetchSource(serverId)`
+
+Extracts the streaming link (m3u8) for a specific server ID.
+
+```javascript
+const source = await flixhq.fetchSource("server-id-54321");
+/* Returns:
+{
+  source: "https://.../master.m3u8",
+  type: "hls",
+  encrypted: false
+}
+*/
+
+```
+
+## Dependencies
+
+* **Axios**: For HTTP requests.
+* **Cheerio**: For DOM parsing and scraping.
+
+## Disclaimer
+
+This library is for educational purposes only. The authors do not endorse or promote copyright infringement. Users are responsible for ensuring they comply with local laws and terms of service of the target websites.
+
+```
+
+```

package/index.js

@@ -0,0 +1,3 @@
+const FlixHQ = require('./src/FlixHQ');
+
+module.exports = FlixHQ;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@sn5u/flixhq-api",
+  "version": "1.0.0",
+  "description": "A robust Node.js API for scraping movies, TV shows, and streaming sources from FlixHQ.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/staticsenju/flixhq-api.git"
+  },
+  "keywords": [
+    "flixhq",
+    "movie-api",
+    "scraper",
+    "streaming",
+    "crawler"
+  ],
+  "author": "staticsenju",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "cheerio": "^1.0.0-rc.12"
+  }
+}

package/src/FlixHQ.js

@@ -0,0 +1,257 @@
+const axios = require('axios');
+const cheerio = require('cheerio');
+const { URL } = require('url');
+
+class FlixHQ {
+  constructor() {
+    this.baseUrl = 'https://flixhq.to';
+    this.headers = {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36',
+      'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+      'X-Requested-With': 'XMLHttpRequest'
+    };
+  }
+
+  _parseGrid($) {
+    const items = [];
+    $('.flw-item').each((_, element) => {
+      const $el = $(element);
+      const $link = $el.find('.film-name a');
+      const title = $link.text().trim();
+      const href = $link.attr('href') || '';
+      const slug = href.replace(/^\//, ''); 
+      const poster = $el.find('img').attr('data-src') || $el.find('img').attr('src');
+      
+      const yearRaw = $el.find('.fdi-item').first().text().trim();
+      const year = parseInt(yearRaw) || null;
+      
+      const duration = $el.find('.fdi-duration').text().trim() || $el.find('.fdi-item').eq(2).text().trim();
+      const quality = $el.find('.film-poster-quality').text().trim();
+      
+      let type = 'movie';
+      if (href.includes('/tv/') || $el.find('.fdi-type').text().trim() === 'TV') {
+        type = 'tv';
+      }
+
+      if (title && slug) {
+        items.push({ 
+          id: slug.split('-').pop(), 
+          title, slug, poster, year, duration, quality, type 
+        });
+      }
+    });
+    return items;
+  }
+
+  async fetchHome() {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/home`, { headers: this.headers });
+      const $ = cheerio.load(data);
+      const trendingMovies = [];
+      $('#trending-movies .flw-item').each((_, el) => trendingMovies.push(this._parseSingleItem($(el), 'movie')));
+      const trendingTV = [];
+      $('#trending-tv .flw-item').each((_, el) => trendingTV.push(this._parseSingleItem($(el), 'tv')));
+      const latestMovies = [];
+      const latestTV = [];
+      $('.block_area').each((_, block) => {
+        const heading = $(block).find('.cat-heading').text().trim();
+        if (heading === 'Latest Movies') $(block).find('.flw-item').each((_, el) => latestMovies.push(this._parseSingleItem($(el), 'movie')));
+        else if (heading === 'Latest TV Shows') $(block).find('.flw-item').each((_, el) => latestTV.push(this._parseSingleItem($(el), 'tv')));
+      });
+      return { trendingMovies, trendingTV, latestMovies, latestTV };
+    } catch (e) { return {}; }
+  }
+
+  _parseSingleItem($el, forcedType) {
+    const title = $el.find('.film-name a').text().trim();
+    const href = $el.find('.film-name a').attr('href') || '';
+    const slug = href.replace(/^\//, '');
+    const poster = $el.find('img').attr('data-src') || $el.find('img').attr('src');
+    const quality = $el.find('.film-poster-quality').text().trim();
+    const year = parseInt($el.find('.fdi-item').first().text().trim()) || null;
+    return {
+      id: slug.split('-').pop(),
+      title, slug, poster, year, quality,
+      type: forcedType || (href.includes('/tv/') ? 'tv' : 'movie')
+    };
+  }
+
+  async fetchMovies(page = 1) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/movie?page=${page}`, { headers: this.headers });
+      return this._parseGrid(cheerio.load(data));
+    } catch (e) { return []; }
+  }
+
+  async fetchTVShows(page = 1) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/tv-show?page=${page}`, { headers: this.headers });
+      return this._parseGrid(cheerio.load(data));
+    } catch (e) { return []; }
+  }
+
+  async fetchTopIMDB(type = 'all', page = 1) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/top-imdb?type=${type}&page=${page}`, { headers: this.headers });
+      return this._parseGrid(cheerio.load(data));
+    } catch (e) { return []; }
+  }
+
+  async fetchFilters() {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/movie`, { headers: this.headers });
+      const $ = cheerio.load(data);
+      const genres = [];
+      $('.genre-ids').each((_, el) => genres.push({ id: $(el).val(), name: $(el).next('label').text().trim() }));
+      const countries = [];
+      $('.country-ids').each((_, el) => countries.push({ id: $(el).val(), name: $(el).next('label').text().trim() }));
+      const years = [];
+      $('input[name="release_year"]').each((_, el) => { if ($(el).val() !== 'all') years.push($(el).val()); });
+      return { genres, countries, years, qualities: ['HD', 'SD', 'CAM'] };
+    } catch (e) { return {}; }
+  }
+
+  async fetchGenres() { const f = await this.fetchFilters(); return f.genres || []; }
+  async fetchCountries() { const f = await this.fetchFilters(); return f.countries || []; }
+
+  async filter(type, value, page = 1) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/${type}/${value}?page=${page}`, { headers: this.headers });
+      return this._parseGrid(cheerio.load(data));
+    } catch (e) { return []; }
+  }
+
+  async search(query) {
+    try {
+      const formatted = query.trim().replace(/[\s\W]+/g, '-');
+      const { data } = await axios.get(`${this.baseUrl}/search/${formatted}`, { headers: this.headers });
+      return this._parseGrid(cheerio.load(data));
+    } catch (error) { return []; }
+  }
+
+  async getDetails(slug) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/${slug}`, { headers: this.headers });
+      const $ = cheerio.load(data);
+      const getRow = (label) => $('.row-line').filter((_, e) => $(e).find('.type').text().trim() === label).text().replace(label, '').trim();
+      const released = getRow('Released:');
+      return {
+        id: slug.split('-').pop(),
+        title: $('.heading-name a').text().trim(),
+        year: released ? parseInt(released.substring(0, 4)) : null,
+        description: $('.description').text().trim() || '',
+        country: getRow('Country:'),
+        released,
+        genres: $('.row-line').filter((_, e) => $(e).find('.type').text().includes('Genre')).find('a').map((_, el) => $(el).text().trim()).get(),
+        poster: $('.film-poster img').attr('src')
+      };
+    } catch (error) { return null; }
+  }
+
+  async getSeasons(slug) {
+    try {
+      const id = slug.split('-').pop(); 
+      const { data } = await axios.get(`${this.baseUrl}/ajax/season/list/${id}`, { headers: this.headers });
+      const $ = cheerio.load(data);
+      return $('.dropdown-item.ss-item').map((_, el) => ({
+        season_number: parseInt($(el).text().replace('Season ', ''), 10) || 0,
+        season_id: $(el).attr('data-id'),
+        name: $(el).text().trim()
+      })).get();
+    } catch (error) { return []; }
+  }
+
+  async getEpisodes(seasonId) {
+    try {
+      const { data } = await axios.get(`${this.baseUrl}/ajax/season/episodes/${seasonId}`, { headers: this.headers });
+      const $ = cheerio.load(data);
+      return $('.nav-item .eps-item').map((_, el) => {
+        const titleRaw = $(el).attr('title');
+        let number = 0, title = titleRaw;
+        if (titleRaw) {
+          const parts = titleRaw.split(':');
+          if (parts.length >= 2) {
+            number = parseInt(parts[0].replace('Eps', '').trim(), 10) || 0;
+            title = parts.slice(1).join(':').trim();
+          }
+        }
+        return { id: $(el).attr('data-id'), number, title };
+      }).get();
+    } catch (error) { return []; }
+  }
+  
+  async getServers(contentId, type = 'tv') {
+    try {
+      const url = type === 'movie' ? `${this.baseUrl}/ajax/episode/list/${contentId}` : `${this.baseUrl}/ajax/episode/servers/${contentId}`;
+      const { data } = await axios.get(url, { headers: this.headers });
+      const $ = cheerio.load(data);
+      const servers = [];
+      $('.nav-item a').each((_, el) => {
+        const $el = $(el);
+        const id = $el.attr('data-id') || $el.attr('data-linkid');
+        const name = $el.attr('title') || $el.find('span').text().trim();
+        if (id) servers.push({ server_id: id, name: name.replace('Server ', '') });
+      });
+      return servers;
+    } catch (error) { return []; }
+  }
+
+  async extractFromEmbed(embedUrl) {
+    try {
+      const parsed = new URL(embedUrl);
+      const embedHost = `${parsed.protocol}//${parsed.host}`;
+      
+      const { data: html } = await axios.get(embedUrl, { 
+        headers: { 'Referer': this.baseUrl, 'User-Agent': this.headers['User-Agent'] } 
+      });
+
+      let nonceMatch = html.match(/\b[a-zA-Z0-9]{48}\b/) ||
+                       html.match(/\b([a-zA-Z0-9]{16})\b.*?\b([a-zA-Z0-9]{16})\b.*?\b([a-zA-Z0-9]{16})\b/);
+
+      if (!nonceMatch) throw new Error("Encryption key not found in embed.");
+      const nonce = nonceMatch.length === 4 ? nonceMatch.slice(1).join("") : nonceMatch[0];
+
+      const fileId = embedUrl.substring(embedUrl.lastIndexOf("/") + 1).split("?")[0];
+      const apiUrl = `${embedHost}/embed-1/v3/e-1/getSources?id=${fileId}&_k=${nonce}`;
+      
+      const { data: apiRes } = await axios.get(apiUrl, { 
+        headers: { 
+          'Referer': embedHost + '/', 
+          'X-Requested-With': 'XMLHttpRequest',
+          'User-Agent': this.headers['User-Agent']
+        } 
+      });
+
+      if (!apiRes.sources || !apiRes.sources.length) throw new Error("No sources returned from provider.");
+
+      return {
+        source: apiRes.sources[0].file,
+        type: apiRes.sources[0].type || 'hls',
+        tracks: apiRes.tracks || [],
+        encrypted: apiRes.encrypted || false
+      };
+
+    } catch (error) {
+      console.error(`[Extractor] Error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async fetchSource(serverId) {
+    try {
+      const url = `${this.baseUrl}/ajax/episode/sources/${serverId}`;
+      const { data } = await axios.get(url, { headers: this.headers });
+      
+      const link = data.link; 
+      if (!link) throw new Error("No embed link found for this server.");
+
+      return await this.extractFromEmbed(link);
+
+    } catch (error) {
+      console.error(`[FlixHQ] Source Fetch Error: ${error.message}`);
+      return null;
+    }
+  }
+}
+
+module.exports = FlixHQ;