instaview 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ecbb088043452c55b479846568262489b6c217798de96ccc0acdc7a6dfcfffb
+  data.tar.gz: b3353cca7a6219a42e4d5c31de08a3136b6760ba8f7fd3fc732febcb1881dd04
+SHA512:
+  metadata.gz: 4430729542295f37cd35935cbb5589edf796c0940d87153281305c249697b1eaa257f4dba81dd8c15250954d17b8962fa56113d8d2ad3609d712e0f266243f8b
+  data.tar.gz: e1977fc370f81854906d66d983e5a08a3bb49aeacb1ae4faa9a2d1c144584ab3299588377bd10e829649cb86026be3e17e01b4c18865ce138d05748f32774904

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-09-30
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+Code of Conduct & Legal Disclaimer
+
+This project is provided as-is for scientific and research purposes only.
+
+Disclaimer of Liability
+
+The author does not assume and hereby disclaims any responsibility or liability for any use, misuse, or consequences—direct or indirect—arising from this code.
+
+You are solely responsible for anything you do with it, including modifying, distributing, or deploying it.
+
+The author does not provide any warranty, express or implied, and does not guarantee fitness for a particular purpose, safety, legality, or correctness of the code in any jurisdiction.
+
+Use at your own risk.
+
+No Support, No Warranty
+
+This is a personal project. There is no official support, no community, and no maintenance commitment.
+
+No Restrictions on Use
+
+You are free to use, modify, redistribute, or ignore this project as you see fit. The author does not care how you use it and takes no responsibility for what you do with it.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nicolas Reiner
+
+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.

data/README.md

@@ -0,0 +1,202 @@
+# Instaview
+
+A Ruby gem that uses Selenium WebDriver to scrape Instagram stories and media from third-party services like StoriesIG. This gem provides a programmatic interface to fetch Instagram content without using the official Instagram API.
+
+## Features
+
+- Scrapes Instagram stories and media using Selenium WebDriver
+- Targets StoriesIG.info for anonymous Instagram viewing
+- Extracts media items with images, captions, download links, and metadata
+- Headless browser automation with fallback HTTP method
+- JSON output format with structured data
+- Command-line interface with multiple methods
+- Built-in local JSON cache with 12h TTL and async fetching
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'instaview'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install instaview
+
+## Setup
+
+After installation, you may need to install Chrome/Chromium for the Selenium method:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install chromium-browser
+
+# Or run the setup script
+./bin/setup_selenium
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Test the gem
+ruby bin/instaview test
+
+# Using the Selenium method (default)
+ruby bin/instaview instagram
+
+# Using the HTTP method (fallback/diagnostic)
+ruby bin/instaview instagram http
+
+# Or if installed as a gem
+instaview username_here http
+```
+
+### Ruby Code
+
+```ruby
+require 'instaview'
+
+# Test connectivity
+Instaview.test_connectivity
+
+# Cache-first with 12h TTL; falls back to fetch when stale/missing
+result = Instaview.get_from_cache_or_async("instagram")
+
+# Cache-only (no network); returns nil if stale/missing
+cached = Instaview.load_from_cache_only("instagram")
+
+# Start an async fetch and get the result later
+t = Instaview.fetch_data_async("instagram", method: :selenium)
+result = t.value  # waits for completion
+
+puts result
+```
+
+### Example Output
+
+#### Selenium Method (Full Automation)
+```json
+{
+  "username": "instagram",
+  "method": "selenium_storiesig",
+  "page_state": "media_found",
+  "media_items_found": 3,
+  "media_items": [
+    {
+      "image_url": "https://media.storiesig.info/get?__sig=...",
+      "alt_text": "preview",
+      "caption": "Some caption text.",
+      "download_url": "https://media.storiesig.info/get?__sig=...",
+      "likes": "8",
+      "time": "2 weeks ago",
+      "time_title": "2025-09-13T08:20:20Z"
+    }
+  ],
+  "all_images": [
+    "https://media.storiesig.info/get?__sig=...",
+    "https://cdn.example.com/asset.jpg"
+  ],
+  "download_links": [
+    "https://media.storiesig.info/get?__sig=..."
+  ],
+  "error_message": null,
+  "success": true,
+  "debug_info": {
+    "total_images": 25,
+    "total_links": 80
+  }
+  /* When served from cache, the top-level object may also include:
+     "cached": true
+  */
+}
+```
+
+#### HTTP Method (Page Analysis)
+```json
+{
+  "username": "instagram",
+  "method": "simple_http_curl",
+  "forms_found": 1,
+  "inputs_found": 1,
+  "sample_images": [
+    "https://cdn.example.com/image1.jpg",
+    "https://cdn.example.com/image2.jpg"
+  ],
+  "message": "Simple HTTP method using curl - shows page structure. For full automation use selenium method."
+}
+```
+
+## Caching
+
+Instaview stores successful results as JSON cache files per username. By default:
+
+- Cache directory: `~/.cache/instaview` (override with `INSTAVIEW_CACHE_DIR`)
+- File name: `<username>.json`
+- Default TTL: 12 hours
+
+You will see `"cached": true` in the JSON when the result was served from cache.
+
+## Dependencies
+
+- Ruby >= 3.2.0
+- selenium-webdriver (~> 4.0)
+- httparty (~> 0.21)
+- nokogiri (~> 1.15)
+- json (~> 2.0)
+- curl (system dependency)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Troubleshooting
+
+### Selenium Issues
+
+If you encounter issues with Selenium WebDriver:
+
+1. Make sure Chrome/Chromium is installed:
+   ```bash
+   sudo apt-get install chromium-browser
+   # or
+   ./bin/setup_selenium
+   ```
+
+2. Use the HTTP method as a fallback:
+   ```bash
+   instaview username http
+   ```
+
+3. Check if the selectors need updating (websites change frequently)
+
+### General Issues
+
+- Some sites have anti-bot measures that may block automated requests
+- The HTTP method provides basic page structure analysis
+- For full automation, Selenium is needed but may face restrictions
+- If you see Selenium logs on every run, it likely means cache is empty or stale; run twice within 12h to observe cached responses.
+
+## Legal Notice
+
+This gem is for educational purposes only. Please respect Instagram's terms of service and the terms of service of any third-party websites you scrape. The authors are not responsible for any misuse of this software.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nicolasreiner/instaview. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nicolasreiner/instaview/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Instaview project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nicolasreiner/instaview/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/instaview/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Instaview
+  VERSION = "0.1.0"
+end

data/lib/instaview.rb

@@ -0,0 +1,489 @@
+# frozen_string_literal: true
+
+require_relative "instaview/version"
+require 'selenium-webdriver'
+require 'nokogiri'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'fileutils'
+require 'time'
+
+module Instaview
+  class Error < StandardError; end
+  
+  # @description
+  #   Default accessor that returns data for a username. Tries cache first (12h TTL),
+  #   otherwise performs an async fetch and returns the fetched result.
+  # @Parameter
+  #   username: String - Instagram username to retrieve data for (required)
+  # @Return values
+  #   Hash - Parsed result of the scraping, potentially annotated with `:cached => true`
+  # @Errors
+  #   ArgumentError - if `username` is nil or empty
+  def self.getData(username = nil)
+    # Default data accessor: try cache first (12h TTL), otherwise fetch asynchronously and return result
+    raise ArgumentError, "username is required" if username.nil? || username.to_s.strip.empty?
+    get_from_cache_or_async(username, max_age_hours: 12)
+  end
+
+  # @description
+  #   Start an asynchronous fetch for the given username and write the result to cache on success.
+  # @Parameter
+  #   username: String - Instagram username (required)
+  #   method: Symbol - :selenium (default) or :simple_http to choose the scraping backend
+  # @Return values
+  #   Thread - The started thread; `thread.value` returns the Hash result when finished
+  # @Errors
+  #   ArgumentError - if `username` is nil or empty
+  #   RuntimeError or StandardError - on scraping failures raised inside the thread when joining
+  def self.fetch_data_async(username, method: :selenium)
+    raise ArgumentError, "username is required" if username.nil? || username.to_s.strip.empty?
+
+    Thread.new do
+      begin
+        result = case method
+                 when :selenium
+                   scrape_instagram_stories(username)
+                 when :simple_http
+                   scrape_with_simple_http(username)
+                 else
+                   scrape_instagram_stories(username)
+                 end
+
+        # Persist to cache on success
+        begin
+          write_to_cache(username, result)
+        rescue => e
+          warn "Instaview: failed to write cache for #{username}: #{e.message}"
+        end
+
+        result
+      rescue => e
+        warn "Instaview: async fetch failed for #{username}: #{e.message}"
+        raise
+      end
+    end
+  end
+
+  # @description
+  #   Try to load from local cache; if missing or older than the given TTL, fetch via async and return the fresh result.
+  # @Parameter
+  #   username: String - Instagram username (required)
+  #   max_age_hours: Integer - Cache TTL in hours (default: 12)
+  #   method: Symbol - :selenium (default) or :simple_http
+  # @Return values
+  #   Hash - Cached or freshly fetched data; cached results will include `:cached => true`
+  # @Errors
+  #   ArgumentError - if `username` is nil or empty
+  def self.get_from_cache_or_async(username, max_age_hours: 12, method: :selenium)
+    max_age_seconds = (max_age_hours.to_i * 3600)
+    cached = read_from_cache(username, max_age_seconds: max_age_seconds)
+    if cached
+      puts "Using cached data for #{username}"
+      return cached
+    end
+    puts "No valid cache found for #{username}, fetching data..."
+    t = fetch_data_async(username, method: method)
+    t.value # join and return result
+  end
+
+  # @description
+  #   Return cached data if present and fresh; otherwise return nil. This method does not perform network I/O.
+  # @Parameter
+  #   username: String - Instagram username (required)
+  #   max_age_hours: Integer - Cache TTL in hours (default: 12)
+  # @Return values
+  #   Hash or nil - Cached data Hash if fresh; nil if missing or stale
+  # @Errors
+  #   ArgumentError - if `username` is nil or empty
+  def self.load_from_cache_only(username, max_age_hours: 12)
+    raise ArgumentError, "username is required" if username.nil? || username.to_s.strip.empty?
+    max_age_seconds = (max_age_hours.to_i * 3600)
+    read_from_cache(username, max_age_seconds: max_age_seconds)
+  end
+
+  # --- Cache helpers ---
+  # @description
+  #   Resolve the directory used to store cache files.
+  # @Parameter
+  #   None
+  # @Return values
+  #   String - Absolute path to the cache directory; defaults to ~/.cache/instaview, overridable by INSTAVIEW_CACHE_DIR
+  # @Errors
+  #   None
+  def self.cache_dir
+    ENV['INSTAVIEW_CACHE_DIR'] || File.join(Dir.home, ".cache", "instaview")
+  end
+
+  # @description
+  #   Compute the cache file path for a given username.
+  # @Parameter
+  #   username: String - Instagram username
+  # @Return values
+  #   String - Full path to the JSON cache file for the username
+  # @Errors
+  #   None
+  def self.cache_file_for(username)
+    sanitized = username.to_s.gsub(/[^a-zA-Z0-9_\-.]/, '_')
+    File.join(cache_dir, "#{sanitized}.json")
+  end
+
+  # @description
+  #   Read a cached result for username if the file exists and is within the max age.
+  # @Parameter
+  #   username: String - Instagram username
+  #   max_age_seconds: Integer - Maximum cache age in seconds (default: 43_200 => 12h)
+  # @Return values
+  #   Hash or nil - Parsed JSON data with `:cached => true` added, or nil if stale/missing/corrupt
+  # @Errors
+  #   JSON::ParserError is rescued internally; returns nil when parse fails
+  def self.read_from_cache(username, max_age_seconds: 43_200)
+    path = cache_file_for(username)
+    return nil unless File.exist?(path)
+
+    age = Time.now - File.mtime(path)
+    return nil if age > max_age_seconds
+
+    content = File.read(path)
+    data = JSON.parse(content, symbolize_names: true)
+    # annotate so callers can tell it came from cache
+    if data.is_a?(Hash)
+      data[:cached] = true
+    end
+    data
+  rescue JSON::ParserError
+    nil
+  end
+
+  # @description
+  #   Write the provided data Hash to the cache file for the username.
+  # @Parameter
+  #   username: String - Instagram username
+  #   data: Hash - Data to persist as JSON
+  # @Return values
+  #   true - On success
+  # @Errors
+  #   StandardError - on underlying file I/O @errors
+  def self.write_to_cache(username, data)
+    FileUtils.mkdir_p(cache_dir)
+    File.write(cache_file_for(username), JSON.pretty_generate(data))
+    true
+  end
+
+  # @description
+  #   Use Selenium WebDriver to automate StoriesIG and extract media details for a username.
+  # @Parameter
+  #   username: String - Instagram username (required)
+  # @Return values
+  #   Hash - Structured result including extracted media and metadata
+  # @Errors
+  #   StandardError - on Selenium/WebDriver failures or selector timeouts
+  def self.scrape_instagram_stories(username = nil)
+    target_username = username || ARGV[0] # pass username as argument
+
+    begin
+      # Setup Selenium WebDriver with headless Chrome
+      options = Selenium::WebDriver::Chrome::Options.new
+      options.add_argument('--headless=new')
+      options.add_argument('--no-sandbox')
+      options.add_argument('--disable-dev-shm-usage')
+      options.add_argument('--disable-gpu')
+      options.add_argument('--disable-extensions')
+      options.add_argument('--disable-background-timer-throttling')
+      options.add_argument('--disable-backgrounding-occluded-windows')
+      options.add_argument('--disable-renderer-backgrounding')
+      options.add_argument('--window-size=1920,1080')
+      options.add_argument('--remote-debugging-port=9222')
+      options.add_argument('--user-data-dir=/tmp/chrome-user-data')
+
+      # Try different Chrome/Chromium binaries
+      chrome_paths = [
+        "/snap/bin/chromium",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/usr/bin/google-chrome"
+      ]
+      
+      chrome_binary = chrome_paths.find { |path| File.exist?(path) }
+      
+      if chrome_binary
+        options.binary = chrome_binary
+        puts "Using Chrome binary: #{chrome_binary}"
+      end
+      
+      driver = Selenium::WebDriver.for :chrome, options: options
+
+      # 1) Go to StoriesIG homepage
+      driver.navigate.to "https://storiesig.info/"
+      sleep 2
+
+      # 2) Find the specific search input for StoriesIG
+      puts "Looking for search input..."
+      input_element = nil
+      
+      # Wait for page to load and find the specific input
+      wait = Selenium::WebDriver::Wait.new(timeout: 10)
+      
+      begin
+        input_element = wait.until do
+          element = driver.find_element(:css, 'input.search.search-form__input[placeholder*="username"]')
+          element if element.displayed?
+        end
+      rescue Selenium::WebDriver::Error::TimeoutError
+        raise "Search input not found with selector: input.search.search-form__input"
+      end
+
+      puts "Found search input, entering username: #{target_username}"
+      input_element.clear
+      input_element.send_keys(target_username)
+
+      # 3) Click the specific search button
+      puts "Looking for search button..."
+      begin
+        button_element = driver.find_element(:css, 'button.search-form__button')
+        puts "Found search button, clicking..."
+        button_element.click
+      rescue Selenium::WebDriver::Error::NoSuchElementError
+        puts "Search button not found, trying Enter key..."
+        input_element.send_keys(:return)
+      end
+
+      # 4) Wait for results to load and check different possible outcomes
+      puts "Waiting for results to load..."
+      sleep 3
+      
+      # Check for various possible page states
+      page_state = "unknown"
+      error_message = nil
+      
+      # Check if media items loaded
+      media_items = driver.find_elements(:css, 'li.profile-media-list__item')
+      if media_items.length > 0
+        page_state = "media_found"
+        puts "Found #{media_items.length} media items!"
+      else
+        # Check for error messages or other states
+        sleep 2  # Give it more time
+        media_items = driver.find_elements(:css, 'li.profile-media-list__item')
+        
+        if media_items.length > 0
+          page_state = "media_found_delayed"
+          puts "Found #{media_items.length} media items after delay!"
+        else
+          # Look for common error indicators
+          error_selectors = [
+            '.error', '.alert', '.warning', 
+            '[class*="error"]', '[class*="not-found"]',
+            'p:contains("not found")', 'div:contains("error")'
+          ]
+          
+          error_found = false
+          error_selectors.each do |selector|
+            begin
+              error_elements = driver.find_elements(:css, selector)
+              if error_elements.any?
+                error_message = error_elements.first.text
+                error_found = true
+                break
+              end
+            rescue
+              # Continue checking other selectors
+            end
+          end
+          
+          if error_found
+            page_state = "error_found"
+            puts "Error found: #{error_message}"
+          else
+            page_state = "no_media"
+            puts "No media items found, checking page content..."
+          end
+        end
+      end
+
+      # 5) Extract media content from the specific structure
+      html = driver.page_source
+      doc = Nokogiri::HTML(html)
+
+      # Extract specific media items using the provided selector
+      media_list_items = doc.css('li.profile-media-list__item')
+      
+      extracted_media = []
+      media_list_items.each_with_index do |item, index|
+        media_data = {}
+        
+        # Extract image source
+        img_element = item.css('.media-content__image').first
+        if img_element
+          media_data[:image_url] = img_element['src']
+          media_data[:alt_text] = img_element['alt']
+        end
+        
+        # Extract caption
+        caption_element = item.css('.media-content__caption').first
+        media_data[:caption] = caption_element&.text&.strip
+        
+        # Extract download link
+        download_element = item.css('a.button.button--filled.button__download').first
+        media_data[:download_url] = download_element['href'] if download_element
+        
+        # Extract metadata
+        like_element = item.css('.media-content__meta-like').first
+        media_data[:likes] = like_element&.text&.strip
+        
+        time_element = item.css('.media-content__meta-time').first
+        media_data[:time] = time_element&.text&.strip
+        media_data[:time_title] = time_element['title'] if time_element
+        
+        extracted_media << media_data unless media_data.empty?
+      end
+
+      # Also extract any general images and links
+      all_images = doc.css('img').map { |img| img['src'] }.compact.uniq.reject(&:empty?)
+      all_links = doc.css('a').map { |link| link['href'] }.compact.uniq.reject(&:empty?)
+      download_links = doc.css('a.button__download').map { |link| link['href'] }.compact.uniq
+
+      result = {
+        username: target_username,
+        method: "selenium_storiesig",
+        page_state: page_state,
+        media_items_found: extracted_media.length,
+        media_items: extracted_media,
+        all_images: all_images.select { |img| img.start_with?('http') }.first(10), # Limit output
+        download_links: download_links,
+        error_message: error_message,
+        success: extracted_media.length > 0,
+        debug_info: {
+          total_images: all_images.length,
+          total_links: all_links.length,
+        }
+      }
+
+      # Save screenshot for debugging if needed
+      if ENV['INSTAVIEW_DEBUG']
+        screenshot_path = "/tmp/instaview_debug_#{Time.now.to_i}.png"
+        driver.save_screenshot(screenshot_path)
+        result[:debug_info][:screenshot_path] = screenshot_path
+        puts "Debug screenshot saved to: #{screenshot_path}"
+      end
+
+      puts JSON.pretty_generate(result)
+
+      result
+    rescue => e
+      puts "Error: #{e.message}"
+      puts "Make sure Chrome/Chromium is installed for Selenium WebDriver"
+      raise e
+    ensure
+      driver&.quit
+    end
+  end
+
+  # @description
+  #   Fetch StoriesIG homepage via curl and parse basic page signals (fallback method).
+  # @Parameter
+  #   username: String - Instagram username (required)
+  # @Return values
+  #   Hash - Basic page analysis and sample assets; primarily for diagnostics
+  # @Errors
+  #   ArgumentError - if `username` is nil or empty
+  #   StandardError - if the curl command fails or returns empty content
+  def self.scrape_with_simple_http(username = nil)
+    target_username = username
+    throw ArgumentError, "Username is required for simple HTTP method" if target_username.nil? || target_username.empty?
+    begin
+      # Simple HTTP approach using curl
+      puts "Trying to fetch page with curl..."
+      
+      curl_command = "curl -s -L -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36' 'https://storiesig.info/'"
+      
+      html_content = `#{curl_command}`
+      
+      if $?.success? && !html_content.empty?
+        doc = Nokogiri::HTML(html_content)
+        
+        # Extract basic page information
+        title = doc.css('title').text
+        forms = doc.css('form')
+        inputs = doc.css('input[type="text"], input[name*="user"]')
+        
+        # Look for any existing media or links
+        images = doc.css('img').map { |img| img['src'] }.compact.select { |src| src.start_with?('http') }
+        links = doc.css('a').map { |link| link['href'] }.compact.select { |href| href.include?('instagram') || href.include?('media') }
+        
+        result = {
+          username: target_username,
+          method: "simple_http_curl",
+          forms_found: forms.length,
+          inputs_found: inputs.length,
+          sample_images: images.first(3),
+          message: "Simple HTTP method using curl - shows page structure. For full automation use selenium method."
+        }
+        
+        puts JSON.pretty_generate(result)
+        result
+      else
+        raise "Curl command failed or returned empty content"
+      end
+    rescue => e
+      puts "Error with simple HTTP method: #{e.message}"
+      puts "Try using scrape_instagram_stories method instead"
+      raise e
+    end
+  end
+  
+  # @description
+  #   Verify gem wiring and surface available methods and version info.
+  # @Parameter
+  #   None
+  # @Return values
+  #   Hash - Connectivity report
+  # @Errors
+  #   None
+  def self.test_connectivity
+    # Simple test method to verify the gem works
+    puts "Testing Instaview gem connectivity..."
+    
+    result = {
+      gem_name: "Instaview",
+      version: Instaview::VERSION,
+      methods_available: [
+        "scrape_instagram_stories",
+        "scrape_with_simple_http",
+        "fetch_data_async",
+        "get_from_cache_or_async",
+        "load_from_cache_only",
+        "getData",
+        "test_connectivity"
+      ],
+      status: "OK"
+    }
+    
+    puts JSON.pretty_generate(result)
+    result
+  end
+
+  # @description
+  #   Legacy parsing example for instaview.me; currently a stub.
+  # @Parameter
+  #   None
+  # @Return values
+  #   nil
+  # @Errors
+  #   StandardError - on network/read @errors
+  def self.parseData
+    # Using a third-party web app, to get Instagram data.
+    # Afterwards, we use Nokogiri to parse the HTML.
+    require "nokogiri"
+    require "open-uri"
+
+    url = "https://www.instaview.me/"
+    html = URI.open(url)
+    doc = Nokogiri::HTML(html)
+
+    doc.xpath("//profile-media-list__item").each do |item|
+      puts item.text
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: instaview
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Reiner
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: A Ruby gem that uses Selenium to scrape Instagram stories and media from
+  third-party services
+email:
+- nici.ferd@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/instaview.rb
+- lib/instaview/version.rb
+homepage: https://github.com/nicolasreiner/instaview
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/nicolasreiner/instaview
+  source_code_uri: https://github.com/nicolasreiner/instaview
+  changelog_uri: https://github.com/nicolasreiner/instaview/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Instagram viewer gem using Selenium for scraping Instagram stories and media
+test_files: []