snapsaver-downloader 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# SnapSaver Downloader
+
+[![npm version](https://img.shields.io/npm/v/snapsaver-downloader.svg)](https://www.npmjs.com/package/snapsaver-downloader)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An unofficial Node.js package to download media from Facebook, Instagram, and TikTok using SnapSave API.
+
+## Features
+
+- 📥 Download videos and images from:
+  - Facebook posts, reels, and watch videos
+  - Instagram posts and reels
+  - TikTok videos
+- 📱 Support for multiple quality options (when available)
+- 🌐 URL normalization and validation
+- 🔄 Automatic platform detection
+
+## Installation
+
+```bash
+npm install snapsaver-downloader
+```
+
+Or with yarn:
+
+```bash
+yarn add snapsaver-downloader
+```
+
+## Usage
+
+```typescript
+import { SnapSaver } from 'snapsaver-downloader';
+
+// Example: Download from Facebook
+async function downloadMedia() {
+  try {
+    const result = await SnapSaver('https://www.facebook.com/watch/?v=1377532133417378');
+    
+    if (result.success) {
+      console.log('Media found:', result.data);
+      // Access download URLs:
+      const mediaUrls = result.data?.media?.map(item => item.url);
+      console.log('Download URLs:', mediaUrls);
+    } else {
+      console.error('Error:', result.message);
+    }
+  } catch (error) {
+    console.error('Failed to download:', error);
+  }
+}
+
+downloadMedia();
+```
+
+### Supported URLs
+
+The package supports various URL formats:
+
+#### Facebook
+- `https://www.facebook.com/watch/?v=1234567890`
+- `https://www.facebook.com/share/v/123ABC456/`
+- `https://www.facebook.com/username/videos/1234567890`
+- `https://fb.watch/abcdef123/`
+
+#### Instagram
+- `https://www.instagram.com/p/ABC123def/`
+- `https://www.instagram.com/reel/ABC123def/`
+- URLs with query parameters (e.g., `?utm_source=ig_web_copy_link`)
+
+#### TikTok
+- `https://www.tiktok.com/@username/video/1234567890`
+- `https://vt.tiktok.com/ABCDEF/`
+
+## API Reference
+
+### SnapSaver(url: string): Promise<SnapSaveDownloaderResponse>
+
+The main function to download media from supported social platforms.
+
+#### Parameters
+
+- `url` (string): URL of the social media post to download
+
+#### Returns
+
+Returns a Promise that resolves to a `SnapSaveDownloaderResponse` object:
+
+```typescript
+interface SnapSaveDownloaderResponse {
+  success: boolean;
+  message?: string;
+  data?: SnapSaveDownloaderData;
+}
+
+interface SnapSaveDownloaderData {
+  description?: string;
+  preview?: string;
+  media?: SnapSaveDownloaderMedia[];
+}
+
+interface SnapSaveDownloaderMedia {
+  resolution?: string;
+  shouldRender?: boolean;
+  thumbnail?: string;
+  type?: "image" | "video";
+  url?: string;
+}
+```
+
+#### Response Structure
+
+- `success` - Boolean indicating if the download was successful
+- `message` - Error message (only present when `success` is false)
+- `data` - Result data (only present when `success` is true)
+  - `description` - Description of the post (when available)
+  - `preview` - Preview image URL (when available)
+  - `media` - Array of media objects containing:
+    - `type` - Media type ("video" or "image")
+    - `url` - Direct download URL
+    - `resolution` - Resolution (for videos, when available)
+    - `thumbnail` - Thumbnail URL (for videos, when available)
+    - `shouldRender` - Whether the media needs special rendering
+
+## Utilities
+
+The package exports several utility functions that might be useful:
+
+```typescript
+import { 
+  normalizeURL, 
+  detectPlatformFromURL,
+  fixThumbnail
+} from 'snapsaver-downloader/dist/utils';
+
+// Normalize a URL (add www if missing)
+const normalizedUrl = normalizeURL('https://facebook.com/video/123');
+// Result: 'https://www.facebook.com/video/123'
+
+// Detect platform from URL
+const platform = detectPlatformFromURL('https://www.instagram.com/reel/ABC123/');
+// Result: 'Instagram'
+```
+
+## Limitations
+
+- This package relies on the SnapSave.app service, which may change its API without notice
+- Some platforms may block scraping attempts or change their URL structure
+- For high-volume applications, consider implementing rate limiting
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+This package is not affiliated with, endorsed by, or connected to SnapSave.app or any of the social media platforms it supports. It is provided for educational purposes only. Always respect the terms of service of the platforms you are downloading content from, and ensure you have the right to download and use the content.

package/dist/Download.d.ts

@@ -0,0 +1,17 @@
+import type { SnapSaveDownloaderResponse } from "./types";
+/**
+ * SnapSaver service - orchestrates the workflow but delegates specific tasks
+ */
+export declare class SnapSaverService {
+    private readonly urlValidator;
+    private readonly decoder;
+    private readonly extractor;
+    private readonly apiClient;
+    constructor();
+    /**
+     * Main method to download media from social platforms via SnapSave
+     * @param url URL of the social media post to download
+     * @returns Response containing success status and download data
+     */
+    download(url: string): Promise<SnapSaveDownloaderResponse>;
+}

package/dist/Download.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapSaverService = void 0;
+const cheerio_1 = require("cheerio");
+const utils_1 = require("./utils");
+/**
+ * URL Validator class - responsible for validating URLs against supported platforms
+ */
+class UrlValidator {
+    constructor(regexes = [utils_1.facebookRegex, utils_1.instagramRegex, utils_1.tiktokRegex]) {
+        this.supportedRegexes = regexes;
+    }
+    /**
+     * Validates if the URL is from a supported platform
+     * @param url URL to validate
+     * @returns Boolean indicating if the URL is supported
+     */
+    isValid(url) {
+        return this.supportedRegexes.some(regex => url.match(regex));
+    }
+}
+/**
+ * SnapSave Decoder class - responsible for all decoding and decryption logic
+ */
+class SnapSaveDecoder {
+    /**
+     * Decodes SnapApp encoded content
+     * @param args Array of arguments from the encoded content
+     * @returns Decoded content
+     */
+    decodeSnapApp(args) {
+        let [encodedContent, u, charMap, subtractValue, base, decodedResult] = args;
+        /**
+         * Internal decoder function for number conversion
+         */
+        const decodeNumber = (value, fromBase, toBase) => {
+            const charset = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+/".split("");
+            const fromCharset = charset.slice(0, fromBase);
+            const toCharset = charset.slice(0, toBase);
+            // @ts-expect-error - Known limitation in type inference for this algorithm
+            let decimal = value.split("").reverse().reduce((sum, char, index) => {
+                if (fromCharset.indexOf(char) !== -1)
+                    return sum += fromCharset.indexOf(char) * (Math.pow(fromBase, index));
+                return sum;
+            }, 0);
+            let result = "";
+            while (decimal > 0) {
+                result = toCharset[decimal % toBase] + result;
+                decimal = (decimal - (decimal % toBase)) / toBase;
+            }
+            return result || "0";
+        };
+        decodedResult = "";
+        for (let i = 0, len = encodedContent.length; i < len; i++) {
+            let segment = "";
+            while (encodedContent[i] !== charMap[Number(base)]) {
+                segment += encodedContent[i];
+                i++;
+            }
+            for (let j = 0; j < charMap.length; j++) {
+                segment = segment.replace(new RegExp(charMap[j], "g"), j.toString());
+            }
+            // @ts-expect-error - Known limitation in type inference for this algorithm
+            decodedResult += String.fromCharCode(decodeNumber(segment, base, 10) - subtractValue);
+        }
+        return this.fixEncoding(decodedResult);
+    }
+    /**
+     * Fixes UTF-8 encoding issues in the decoded content
+     */
+    fixEncoding(str) {
+        const bytes = new Uint8Array(str.split("").map(char => char.charCodeAt(0)));
+        return new TextDecoder("utf-8").decode(bytes);
+    }
+    /**
+     * Extracts the encoded arguments from SnapSave HTML response
+     */
+    getEncodedSnapApp(data) {
+        return data.split("decodeURIComponent(escape(r))}(")[1]
+            .split("))")[0]
+            .split(",")
+            .map(v => v.replace(/"/g, "").trim());
+    }
+    /**
+     * Extracts the decoded HTML content from SnapSave response
+     */
+    getDecodedSnapSave(data) {
+        return data.split("getElementById(\"download-section\").innerHTML = \"")[1]
+            .split("\"; document.getElementById(\"inputData\").remove(); ")[0]
+            .replace(/\\(\\)?/g, "");
+    }
+    /**
+     * Decrypts the SnapSave response by chaining the decoding functions
+     * @param data Raw HTML response from SnapSave
+     * @returns Decrypted HTML content
+     */
+    decrypt(data) {
+        return this.getDecodedSnapSave(this.decodeSnapApp(this.getEncodedSnapApp(data)));
+    }
+}
+/**
+ * Media Extractor class - responsible for extracting media from different HTML layouts
+ */
+class MediaExtractor {
+    /**
+     * Extract metadata from HTML content
+     * @param $ Cheerio API instance
+     * @returns Extracted metadata
+     */
+    extractMetadata($) {
+        const data = {};
+        const description = $("span.video-des").text().trim();
+        const preview = $("article.media > figure").find("img").attr("src");
+        if (description)
+            data.description = description;
+        if (preview)
+            data.preview = preview;
+        return data;
+    }
+    /**
+     * Extract media items from table layout
+     * @param $ Cheerio API instance
+     * @returns Array of extracted media
+     */
+    extractTableMedia($) {
+        const media = [];
+        $("tbody > tr").each((_, el) => {
+            var _a;
+            const $el = $(el);
+            const $td = $el.find("td");
+            const resolution = $td.eq(0).text();
+            let mediaUrl = $td.eq(2).find("a").attr("href") || $td.eq(2).find("button").attr("onclick");
+            const shouldRender = /get_progressApi/ig.test(mediaUrl || "");
+            if (shouldRender) {
+                mediaUrl = "https://snapsave.app" + ((_a = /get_progressApi\('(.*?)'\)/.exec(mediaUrl || "")) === null || _a === void 0 ? void 0 : _a[1]) || mediaUrl;
+            }
+            media.push({
+                resolution,
+                ...(shouldRender ? { shouldRender } : {}),
+                url: mediaUrl,
+                type: resolution ? "video" : "image"
+            });
+        });
+        return media;
+    }
+    /**
+     * Extract media items from card layout
+     * @param $ Cheerio API instance
+     * @returns Array of extracted media
+     */
+    extractCardMedia($) {
+        const media = [];
+        $("div.card").each((_, el) => {
+            const cardBody = $(el).find("div.card-body");
+            const aText = cardBody.find("a").text().trim();
+            const url = cardBody.find("a").attr("href");
+            const type = aText === "Download Photo" ? "image" : "video";
+            media.push({
+                url,
+                type
+            });
+        });
+        return media;
+    }
+    /**
+     * Extract media from simple layout
+     * @param $ Cheerio API instance
+     * @returns Array of extracted media
+     */
+    extractSimpleMedia($) {
+        const media = [];
+        const url = $("a").attr("href") || $("button").attr("onclick");
+        const aText = $("a").text().trim();
+        const type = aText === "Download Photo" ? "image" : "video";
+        media.push({
+            url,
+            type
+        });
+        return media;
+    }
+    /**
+     * Extract media from download items layout
+     * @param $ Cheerio API instance
+     * @returns Array of extracted media
+     */
+    extractDownloadItemsMedia($) {
+        const media = [];
+        $("div.download-items").each((_, el) => {
+            const itemThumbnail = $(el).find("div.download-items__thumb > img").attr("src");
+            const itemBtn = $(el).find("div.download-items__btn");
+            const url = itemBtn.find("a").attr("href");
+            const spanText = itemBtn.find("span").text().trim();
+            const type = spanText === "Download Photo" ? "image" : "video";
+            media.push({
+                url,
+                ...(type === "video" && itemThumbnail ? {
+                    thumbnail: (0, utils_1.fixThumbnail)(itemThumbnail)
+                } : {}),
+                type
+            });
+        });
+        return media;
+    }
+}
+/**
+ * SnapSave API Client - responsible for making API requests
+ */
+class SnapSaveApiClient {
+    constructor(apiUrl = "https://snapsave.app/action.php?lang=en") {
+        this.apiUrl = apiUrl;
+    }
+    /**
+     * Make a request to the SnapSave API
+     * @param url URL to download from
+     * @returns Raw HTML response
+     */
+    async fetchMedia(url) {
+        // Prepare request to SnapSave API
+        const formData = new URLSearchParams();
+        formData.append("url", (0, utils_1.normalizeURL)(url));
+        const response = await fetch(this.apiUrl, {
+            method: "POST",
+            headers: {
+                "accept": "*/*",
+                "content-type": "application/x-www-form-urlencoded",
+                "origin": "https://snapsave.app",
+                "referer": "https://snapsave.app/",
+                "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0"
+            },
+            body: formData
+        });
+        // Return raw response
+        return response.text();
+    }
+}
+/**
+ * SnapSaver service - orchestrates the workflow but delegates specific tasks
+ */
+class SnapSaverService {
+    constructor() {
+        this.urlValidator = new UrlValidator();
+        this.decoder = new SnapSaveDecoder();
+        this.extractor = new MediaExtractor();
+        this.apiClient = new SnapSaveApiClient();
+    }
+    /**
+     * Main method to download media from social platforms via SnapSave
+     * @param url URL of the social media post to download
+     * @returns Response containing success status and download data
+     */
+    async download(url) {
+        try {
+            // Validate URL against supported platforms
+            if (!this.urlValidator.isValid(url)) {
+                return {
+                    success: false,
+                    message: "Invalid URL"
+                };
+            }
+            // Fetch media from SnapSave API
+            const html = await this.apiClient.fetchMedia(url);
+            // Decrypt the response
+            const decodedHtml = this.decoder.decrypt(html);
+            // Parse HTML and extract media
+            const $ = (0, cheerio_1.load)(decodedHtml);
+            // Initialize data structure
+            const data = {};
+            let media = [];
+            // Extract data based on the HTML structure
+            if ($("table.table").length || $("article.media > figure").length) {
+                // Extract metadata
+                Object.assign(data, this.extractor.extractMetadata($));
+                // Extract media based on layout
+                if ($("table.table").length) {
+                    media = this.extractor.extractTableMedia($);
+                }
+                else if ($("div.card").length) {
+                    media = this.extractor.extractCardMedia($);
+                }
+                else {
+                    media = this.extractor.extractSimpleMedia($);
+                }
+            }
+            // Extract media from download items layout
+            else if ($("div.download-items").length) {
+                media = this.extractor.extractDownloadItemsMedia($);
+            }
+            // Validate results
+            if (!media.length) {
+                return {
+                    success: false,
+                    message: "No downloadable media found"
+                };
+            }
+            // Add media to data and return
+            data.media = media;
+            return {
+                success: true,
+                data
+            };
+        }
+        catch (error) {
+            console.error("SnapSaver error:", error);
+            return {
+                success: false,
+                message: "Failed to process download request"
+            };
+        }
+    }
+}
+exports.SnapSaverService = SnapSaverService;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { SnapSaveDownloaderResponse } from "./types";
+/**
+ * Main function to download media from social platforms via SnapSave
+ * @param url URL of the social media post to download
+ * @returns Response containing success status and download data
+ */
+export declare const SnapSaver: (url: string) => Promise<SnapSaveDownloaderResponse>;

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapSaver = void 0;
+const Download_1 = require("./Download");
+// Create singleton instance
+const snapSaverInstance = new Download_1.SnapSaverService();
+/**
+ * Main function to download media from social platforms via SnapSave
+ * @param url URL of the social media post to download
+ * @returns Response containing success status and download data
+ */
+const SnapSaver = async (url) => {
+    return snapSaverInstance.download(url);
+};
+exports.SnapSaver = SnapSaver;

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export interface SnapSaveDownloaderMedia {
+    resolution?: string;
+    shouldRender?: boolean;
+    thumbnail?: string;
+    type?: "image" | "video";
+    url?: string;
+}
+export interface SnapSaveDownloaderData {
+    description?: string;
+    preview?: string;
+    media?: SnapSaveDownloaderMedia[];
+}
+export interface SnapSaveDownloaderResponse {
+    success: boolean;
+    message?: string;
+    data?: SnapSaveDownloaderData;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Regular expression patterns for various social media platforms
+ * Each regex is designed to match the URL format for a specific platform
+ */
+export declare const facebookRegex: RegExp;
+export declare const instagramRegex: RegExp;
+export declare const tiktokRegex: RegExp;
+export declare const youtubeRegex: RegExp;
+export declare const twitterRegex: RegExp;
+export declare const normalizeURL: (url: string) => string;
+export declare const fixThumbnail: (url: string) => string;
+export declare const detectPlatformFromURL: (url: string) => string | null;

package/dist/utils.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Regular expression patterns for various social media platforms
+ * Each regex is designed to match the URL format for a specific platform
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPlatformFromURL = exports.fixThumbnail = exports.normalizeURL = exports.twitterRegex = exports.youtubeRegex = exports.tiktokRegex = exports.instagramRegex = exports.facebookRegex = void 0;
+// Facebook URLs including watch, reels, videos, posts and fb.watch short links
+exports.facebookRegex = /^https?:\/\/(?:www\.|web\.|m\.)?facebook\.com\/(watch(\?v=|\/\?v=)[0-9]+(?!\/)|reel\/[0-9]+|[a-zA-Z0-9.\-_]+\/(videos|posts)\/[0-9]+|[0-9]+\/(videos|posts)\/[0-9]+|[a-zA-Z0-9]+\/(videos|posts)\/[0-9]+|share\/(v|r)\/[a-zA-Z0-9]+\/?)([^/?#&]+).*$|^https:\/\/fb\.watch\/[a-zA-Z0-9]+$/;
+// Instagram URLs for posts, reels, stories, tv and share links
+exports.instagramRegex = /^https?:\/\/(?:www\.)?instagram\.com\/(?:p|reel|reels|tv|stories|share)\/([^/?#&]+).*/;
+// TikTok URLs for various formats including user videos, photos and short links
+exports.tiktokRegex = /^https?:\/\/(?:www\.|m\.|vm\.|vt\.)?tiktok\.com\/(?:@[^/]+\/(?:video|photo)\/\d+|v\/\d+|t\/[\w]+|[\w-]+)\/?/i;
+// YouTube URLs for standard watch URLs, shorts and embed links
+exports.youtubeRegex = /^https?:\/\/(?:www\.)?(?:youtube\.com\/(?:watch\?(?:.*&)?v=|shorts\/|embed\/)|youtu\.be\/)([a-zA-Z0-9_-]{11})(?:[?&][^#\s]*)?/;
+// Twitter/X URLs for tweet status links
+exports.twitterRegex = /^https?:\/\/(?:www\.)?(?:twitter\.com|x\.com)\/(?:#!\/)?(?:[\w_]+\/status(?:es)?\/)([0-9]+)(?:[?&][^#\s]*)?/;
+const normalizeURL = (url) => {
+    return /^(https?:\/\/)(?!www\.)[a-z0-9]+/i.test(url)
+        ? url.replace(/^(https?:\/\/)([^./]+\.[^./]+)(\/.*)?$/, "$1www.$2$3")
+        : url;
+};
+exports.normalizeURL = normalizeURL;
+const fixThumbnail = (url) => {
+    const toReplace = "https://snapinsta.app/photo.php?photo=";
+    return url.includes(toReplace) ? decodeURIComponent(url.replace(toReplace, "")) : url;
+};
+exports.fixThumbnail = fixThumbnail;
+const detectPlatformFromURL = (url) => {
+    if (exports.facebookRegex.test(url))
+        return "Facebook";
+    if (exports.instagramRegex.test(url))
+        return "Instagram";
+    if (exports.tiktokRegex.test(url))
+        return "TikTok";
+    if (exports.youtubeRegex.test(url))
+        return "YouTube";
+    if (exports.twitterRegex.test(url))
+        return "Twitter";
+    return null;
+};
+exports.detectPlatformFromURL = detectPlatformFromURL;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "snapsaver-downloader",
+  "version": "1.0.0",
+  "description": "An Unofficial Package to Download From Facebook, TikTok and Instagram. Relais on SnapSave",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gitnasr/snapsaver-dl.git"
+  },
+  "keywords": [
+    "snapsaver",
+    "instagram",
+    "facebook",
+    "twitter"
+  ],
+  "author": "gitnasr",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/gitnasr/snapsaver-dl/issues"
+  },
+  "homepage": "https://github.com/gitnasr/snapsaver-dl#readme",
+  "dependencies": {
+    "cheerio": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^18.0.0",
+    "jest": "^29.7.0",
+    "jest-fetch-mock": "^3.0.3",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "LICENSE",
+    "README.md"
+  ]
+}