hikerapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3984a16a595e5ac7953be0212d6b792ffe42f334cc699c8ac9f08eacd0f597bc
+  data.tar.gz: 8974f4b13520002f7c2cc71be6bad4f28a1aeff1c882102fd799c2fd338cf6c7
+SHA512:
+  metadata.gz: 5000559541b7f8dc4fa2b33b3ff241b0ffab1e3db27e1564cad8ae1b5c2ba6004d18fb576058d7a54a47970a48f45550a1d44e88fa44a1d44826c00a32fba837
+  data.tar.gz: bd0397ee8c291519ded4002997299ee2e0b983b0f18137fa2f829ca9b210bd1764f26805fd70ca3384b679eb5f5b2324d0c52a9f414d9401335c2095c0f93e3e

data/README.md

@@ -0,0 +1,111 @@
+# Hikerapi
+
+A zero-dependency Ruby client for [HikerAPI](https://hikerapi.com/) - an Instagram Data API for developers.
+It uses only Ruby standard library (`Net::HTTP`, `JSON`, `URI`, `Zlib`).
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'hikerapi', path: '../hikerapi' # Or git/gem repository reference
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Configuration
+
+You can provide your HikerAPI key via an environment variable:
+
+```bash
+export HIKER_API_KEY='your_access_key_here'
+```
+
+Or via a Rails initializer or configuration block:
+
+```ruby
+require 'hikerapi'
+
+Hikerapi.configure do |config|
+  config.api_key = 'your_access_key_here'
+  # config.api_base_url = 'https://api.hikerapi.com' # default
+end
+
+client = Hikerapi::Client.new
+```
+
+Or pass it when initializing the client:
+
+```ruby
+client = Hikerapi::Client.new(api_key: 'your_access_key_here')
+```
+
+## Usage
+
+### User Information
+
+```ruby
+client = Hikerapi::Client.new
+
+# Get user info by username
+user = client.user.by_username('nike')
+puts user['pk'] # User ID
+puts user['biography']
+puts user['external_url']
+
+# Get user info by ID
+user = client.user.by_id('1234567')
+
+# Get user info by profile URL
+user = client.user.by_url('https://www.instagram.com/nike/')
+```
+
+### User Medias (Posts) & Cursor Iteration
+
+```ruby
+# Get user posts iterator (by user_id)
+iterator = client.user.medias('787132')
+
+# Get only the first chunk [ items, end_cursor ]:
+items, end_cursor = client.user.medias('787132').each_chunk.first
+# or:
+items, end_cursor = client.user.medias_chunk('787132')
+
+# Iterate chunk-by-chunk with end_cursor:
+client.user.medias('787132').each_chunk do |chunk, end_cursor|
+  puts "Fetched #{chunk.size} posts. Next cursor: #{end_cursor}"
+end
+
+# Iterate item-by-item across all chunks automatically:
+client.user.medias('787132').each do |post|
+  puts post['code']
+end
+
+# Standard Enumerable methods work directly:
+recent_5 = client.user.medias('787132').take(5)
+
+# Fetch user clips / reels
+reels = client.user.clips('nike')
+# or using shortcut:
+reels = client.reels('nike')
+```
+
+### Media Details & Comments
+
+```ruby
+# Fetch comments for a post or reel (by shortcode, media ID, or URL)
+comments = client.media.comments('DalGZj5uimd')
+# or using shortcut:
+comments = client.comments('https://www.instagram.com/p/DalGZj5uimd/')
+
+# Fetch single media details by shortcode
+media = client.media.by_code('DalGZj5uimd')
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/hikerapi/chunk_iterator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hikerapi
+  class ChunkIterator
+    include Enumerable
+
+    attr_reader :options, :fetch_proc
+
+    def initialize(options = {}, &fetch_proc)
+      @options = options.dup
+      @fetch_proc = fetch_proc
+    end
+
+    def fetch_chunk(cursor = options[:end_cursor] || options[:max_id])
+      fetch_proc.call(cursor)
+    end
+    alias page fetch_chunk
+    alias first_chunk fetch_chunk
+
+    def each
+      return to_enum(:each) unless block_given?
+
+      cursor = options[:end_cursor] || options[:max_id]
+
+      loop do
+        chunk, next_cursor = fetch_chunk(cursor)
+        break if chunk.nil? || chunk.empty?
+
+        chunk.each { |item| yield item }
+
+        break if next_cursor.nil? || next_cursor.to_s.empty?
+        break if next_cursor == cursor
+
+        cursor = next_cursor
+      end
+    end
+
+    def each_chunk
+      return to_enum(:each_chunk) unless block_given?
+
+      cursor = options[:end_cursor] || options[:max_id]
+
+      loop do
+        chunk, next_cursor = fetch_chunk(cursor)
+        break if chunk.nil? || chunk.empty?
+
+        yield chunk
+
+        break if next_cursor.nil? || next_cursor.to_s.empty?
+        break if next_cursor == cursor
+
+        cursor = next_cursor
+      end
+    end
+  end
+end

data/lib/hikerapi/client.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'zlib'
+require 'stringio'
+
+module Hikerapi
+  class Client
+    attr_reader :config, :api_key
+
+    def initialize(config = nil, api_key: nil)
+      @config = config || Hikerapi.configuration
+      @api_key = api_key || @config.api_key
+    end
+
+    def user
+      @user ||= User.new(self)
+    end
+
+    def media
+      @media ||= Media.new(self)
+    end
+
+    def posts(username_or_id_or_url, options = {})
+      user.medias(username_or_id_or_url, options)
+    end
+
+    def reels(username_or_id_or_url, options = {})
+      user.clips(username_or_id_or_url, options)
+    end
+
+    def comments(media_id_or_code_or_url, options = {})
+      media.comments(media_id_or_code_or_url, options)
+    end
+
+    def get(endpoint, params = {}, options = {})
+      request(endpoint, method: :get, params: params, options: options)
+    end
+
+    def post(endpoint, params = {}, options = {})
+      request(endpoint, method: :post, params: params, options: options)
+    end
+
+    def request(endpoint, method: :get, params: {}, options: {})
+      current_key = options[:api_key] || api_key
+      if current_key.nil? || current_key.to_s.strip.empty?
+        raise ConfigurationError, "HikerAPI key is missing. Set ENV['HIKER_API_KEY'], configure via Hikerapi.configure { |c| c.api_key = '...' }, or pass api_key: to Client.new"
+      end
+
+      clean_endpoint = endpoint.to_s.start_with?('/') ? endpoint.to_s : "/#{endpoint}"
+      base_url = options[:api_base_url] || config.api_base_url
+      url_str = "#{base_url}#{clean_endpoint}"
+
+      uri = URI.parse(url_str)
+
+      if method == :get
+        uri.query = URI.encode_www_form(params) if params && !params.empty?
+        req = Net::HTTP::Get.new(uri.request_uri)
+      else
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(params) if params && !params.empty?
+      end
+
+      req['x-access-key'] = current_key
+      req['Accept'] = 'application/json'
+      req['Accept-Encoding'] = 'gzip, deflate'
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = options[:open_timeout] || config.open_timeout
+      http.read_timeout = options[:read_timeout] || config.read_timeout
+
+      max_retries = options[:max_retries] || 3
+      retries = 0
+
+      begin
+        res = http.request(req)
+        parse_response(res)
+      rescue APIError => e
+        if e.status == 429 && retries < max_retries
+          retries += 1
+          delay = (res.respond_to?(:[]) && res['Retry-After']) ? res['Retry-After'].to_f : (1.2 * retries)
+          warn "HikerAPI 429 Rate Limited. Retrying in #{delay}s... (attempt #{retries}/#{max_retries})"
+          sleep(delay)
+          retry
+        end
+        raise e
+      end
+    end
+
+    private
+
+    def parse_response(response)
+      body = response.body
+
+      if response['Content-Encoding'] == 'gzip' && body && !body.empty?
+        begin
+          body = Zlib::GzipReader.new(StringIO.new(body)).read
+        rescue Zlib::Error, Zlib::GzipFile::Error
+          # Decompression fallback
+        end
+      elsif response['Content-Encoding'] == 'deflate' && body && !body.empty?
+        begin
+          body = Zlib::Inflate.inflate(body)
+        rescue Zlib::Error
+          # Decompression fallback
+        end
+      end
+
+      parsed = begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        error_msg = if parsed.is_a?(Hash)
+                      parsed['detail'] || parsed['message'] || parsed['error'] || response.message
+                    else
+                      response.message
+                    end
+        raise APIError.new("HikerAPI Error (#{response.code}): #{error_msg}", status: response.code.to_i, response_body: body)
+      end
+
+      parsed
+    end
+  end
+end

data/lib/hikerapi/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hikerapi
+  class Configuration
+    attr_accessor :api_key, :api_base_url, :open_timeout, :read_timeout
+
+    def initialize
+      @api_key = ENV['HIKER_API_KEY']
+      @api_base_url = 'https://api.hikerapi.com'
+      @open_timeout = 15
+      @read_timeout = 60
+    end
+  end
+end

data/lib/hikerapi/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hikerapi
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class APIError < Error
+    attr_reader :status, :response_body
+
+    def initialize(message, status: nil, response_body: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+    end
+  end
+end

data/lib/hikerapi/media.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Hikerapi
+  class Media
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Fetch media details by shortcode
+    # @param code_or_url [String] Post shortcode or URL (e.g. "DalGZj5uimd" or "https://www.instagram.com/p/DalGZj5uimd/")
+    def by_code(code_or_url, options = {})
+      code = extract_shortcode(code_or_url)
+      client.get('/v1/media/by/code', { code: code }.merge(options))
+    end
+
+    # Fetch media details by ID
+    # @param media_id [String, Integer] Media ID
+    def by_id(media_id, options = {})
+      client.get('/v1/media/by/id', { id: media_id }.merge(options))
+    end
+
+    # Fetch media details by URL
+    # @param url [String] Post/reel URL
+    def by_url(url, options = {})
+      client.get('/v1/media/by/url', { url: url }.merge(options))
+    end
+
+    # Fetch comments iterator for a media post or reel
+    # @param media_id_or_code_or_url [String, Integer] Media ID, shortcode, or post URL
+    # @param options [Hash] Additional options (e.g., max_id: '...')
+    def comments(media_id_or_code_or_url, options = {}, &block)
+      iterator = ChunkIterator.new(options) do |cursor|
+        opts = options.dup
+        opts[:max_id] = cursor if cursor && !cursor.to_s.empty?
+        comments_chunk(media_id_or_code_or_url, opts)
+      end
+      block_given? ? iterator.each(&block) : iterator
+    end
+
+    # Fetch a single chunk of comments for a media post or reel
+    # @param media_id_or_code_or_url [String, Integer] Media ID, shortcode, or post URL
+    # @param options [Hash] Additional options
+    def comments_chunk(media_id_or_code_or_url, options = {})
+      params = build_media_param(media_id_or_code_or_url).merge(options)
+      client.get('/v1/media/comments/chunk', params)
+    end
+
+    private
+
+    def extract_shortcode(input)
+      str = input.to_s.strip
+      return str if str.empty?
+
+      if str.include?('/p/') || str.include?('/reel/') || str.include?('/tv/')
+        match = str.match(%r{/(?:p|reel|tv)/([^/?#]+)})
+        return match[1] if match
+      end
+
+      str.split('/').reject(&:empty?).last.to_s.split('?').first
+    end
+
+    def build_media_param(input)
+      str = input.to_s.strip
+      if str.match?(/\A\d+_\d+\z/) || str.match?(/\A\d+\z/)
+        { media_id: str }
+      elsif str.start_with?('http://', 'https://') || str.length < 20
+        code = extract_shortcode(str)
+        { code: code }
+      else
+        { media_id: str }
+      end
+    end
+  end
+end

data/lib/hikerapi/media_iterator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hikerapi
+  class MediaIterator < ChunkIterator
+    attr_reader :user, :user_id
+
+    def initialize(user, user_id, options = {})
+      @user = user
+      @user_id = user_id.to_s
+      super(options) do |cursor|
+        opts = options.dup
+        opts[:end_cursor] = cursor if cursor && !cursor.to_s.empty?
+        user.medias_chunk(user_id, opts)
+      end
+    end
+  end
+end

data/lib/hikerapi/user.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Hikerapi
+  class User
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Fetch user info by username
+    # @param username_or_url [String] Username, @handle, or Instagram profile URL
+    def by_username(username_or_url, options = {})
+      username = extract_username(username_or_url)
+      client.get('/v1/user/by/username', { username: username }.merge(options))
+    end
+
+    # Fetch user info by ID
+    # @param user_id [String, Integer] User ID (pk)
+    def by_id(user_id, options = {})
+      client.get('/v1/user/by/id', { user_id: user_id }.merge(options))
+    end
+
+    # Fetch user info by URL
+    # @param url [String] Instagram profile URL
+    def by_url(url, options = {})
+      client.get('/v1/user/by/url', { url: url }.merge(options))
+    end
+
+    # Fetch user posts (medias) iterator
+    # @param user_id [String, Integer] User ID
+    # @param options [Hash] Additional options (e.g., end_cursor: '...')
+    def medias(user_id, options = {}, &block)
+      iterator = MediaIterator.new(self, user_id, options)
+      block_given? ? iterator.each(&block) : iterator
+    end
+
+    # Fetch a single chunk of user medias with cursor
+    # @param user_id [String, Integer] User ID
+    # @param options [Hash] Additional options (e.g., end_cursor: '...')
+    def medias_chunk(user_id, options = {})
+      params = { user_id: user_id.to_s }.merge(options)
+      params.delete(:end_cursor) if params[:end_cursor].nil? || params[:end_cursor].to_s.empty?
+      client.get('/v1/user/medias/chunk', params)
+    end
+
+
+    # Fetch user clips / reels iterator
+    # @param user_id [String, Integer] User ID
+    # @param options [Hash] Additional options (e.g., end_cursor: '...')
+    def clips(user_id, options = {}, &block)
+      iterator = ChunkIterator.new(options) do |cursor|
+        opts = options.dup
+        opts[:end_cursor] = cursor if cursor && !cursor.to_s.empty?
+        clips_chunk(user_id, opts)
+      end
+      block_given? ? iterator.each(&block) : iterator
+    end
+
+    # Fetch single chunk of user clips / reels
+    # @param user_id [String, Integer] User ID
+    # @param options [Hash] Additional options (e.g., end_cursor: '...')
+    def clips_chunk(user_id, options = {})
+      params = { user_id: user_id.to_s }.merge(options)
+      params.delete(:end_cursor) if params[:end_cursor].nil? || params[:end_cursor].to_s.empty?
+      client.get('/v1/user/clips/chunk', params)
+    end
+
+    # Fetch user about info
+    # @param user_id [String, Integer] User ID
+    def about(user_id, options = {})
+      client.get('/v1/user/about', { user_id: user_id }.merge(options))
+    end
+
+    private
+
+    def extract_username(input)
+      str = input.to_s.strip
+      return str if str.empty?
+
+      if str.start_with?('http://', 'https://')
+        uri = URI.parse(str) rescue nil
+        if uri && uri.path
+          parts = uri.path.split('/').reject(&:empty?)
+          first_part = parts.first
+          return first_part.delete_prefix('@') if first_part && !%w[p reel tv].include?(first_part)
+        end
+      end
+
+      str.split('/').reject(&:empty?).last.to_s.split('?').first.delete_prefix('@')
+    end
+
+    def build_user_param(input)
+      str = input.to_s.strip
+      if str.match?(/\A\d+\z/)
+        { user_id: str }
+      else
+        { username: extract_username(str) }
+      end
+    end
+  end
+end

data/lib/hikerapi/version.rb

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

data/lib/hikerapi.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "hikerapi/version"
+require_relative "hikerapi/error"
+require_relative "hikerapi/configuration"
+require_relative "hikerapi/chunk_iterator"
+require_relative "hikerapi/media_iterator"
+require_relative "hikerapi/user"
+require_relative "hikerapi/media"
+require_relative "hikerapi/client"
+
+module Hikerapi
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configuration=(config)
+      @configuration = config
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: hikerapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- swlkr
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Zero-dependency Ruby client for HikerAPI (https://hikerapi.com/) to fetch
+  Instagram user profile data, posts, reels, and comments.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hikerapi.rb
+- lib/hikerapi/chunk_iterator.rb
+- lib/hikerapi/client.rb
+- lib/hikerapi/configuration.rb
+- lib/hikerapi/error.rb
+- lib/hikerapi/media.rb
+- lib/hikerapi/media_iterator.rb
+- lib/hikerapi/user.rb
+- lib/hikerapi/version.rb
+homepage: https://github.com/swlkr/hikerapi
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for HikerAPI Instagram API
+test_files: []