linkio 1.0.0

data/lib/linkio/utils.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "digest"
+require "uri"
+
+module LinkIO
+  # Stateless helpers for fingerprinting, platform detection and deep link
+  # building. Mirrors the utilities from the Node.js LinkIO backend.
+  module Utils
+    # Characters left unescaped by JavaScript's encodeURIComponent.
+    UNRESERVED = /[^A-Za-z0-9\-_.!~*'()]/n
+
+    module_function
+
+    # Generate a fingerprint from IP + User-Agent for deferred deep linking.
+    # This allows matching users before and after app install.
+    #
+    # @param ip [String]
+    # @param user_agent [String]
+    # @return [String] 32-character hex digest
+    def generate_fingerprint(ip, user_agent)
+      Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
+    end
+
+    # Generate an IP-only fingerprint for cross-browser/app matching.
+    # Less precise but works when User-Agent differs between browser and app.
+    #
+    # @param ip [String]
+    # @return [String] 32-character hex digest
+    def generate_ip_fingerprint(ip)
+      Digest::SHA256.hexdigest(ip.to_s)[0, 32]
+    end
+
+    # Extract the client IP from request data, honouring the X-Forwarded-For
+    # header set by proxies.
+    #
+    # @param forwarded_for [String, nil] value of the X-Forwarded-For header
+    # @param ip [String, nil] framework-resolved remote IP
+    # @param remote_address [String, nil] raw socket remote address
+    # @return [String] the resolved client IP, or "unknown"
+    def client_ip(forwarded_for: nil, ip: nil, remote_address: nil)
+      return forwarded_for.to_s.split(",").first.to_s.strip if forwarded_for && !forwarded_for.to_s.empty?
+
+      value = ip || remote_address
+      value.nil? || value.to_s.empty? ? "unknown" : value.to_s
+    end
+
+    # Detect the platform from a User-Agent string.
+    #
+    # @param user_agent [String, nil]
+    # @return [String]
+    def detect_platform(user_agent)
+      Platform.detect(user_agent)
+    end
+
+    # Parse the query parameters of a URL into a string-keyed hash.
+    #
+    # @param url [String]
+    # @return [Hash{String => String}]
+    def parse_query_params(url)
+      query = URI.parse(url).query
+      return {} if query.nil? || query.empty?
+
+      params = {}
+      URI.decode_www_form(query).each do |key, value|
+        params[key] = if params.key?(key)
+                        Array(params[key]) << value
+                      else
+                        value
+                      end
+      end
+      params
+    rescue URI::InvalidURIError, ArgumentError
+      {}
+    end
+
+    # Build a custom-scheme deep link URI.
+    #
+    # @param scheme [String] e.g. "rokart"
+    # @param path [String] e.g. "link"
+    # @param params [Hash]
+    # @return [String] e.g. "rokart://link?foo=bar"
+    def build_deep_link(scheme, path, params)
+      query = encode_query(params)
+      "#{scheme}://#{path}#{"?#{query}" unless query.empty?}"
+    end
+
+    # URL-encode a params hash into a query string, matching the Node backend's
+    # `encodeURIComponent` behaviour.
+    #
+    # @param params [Hash]
+    # @return [String]
+    def encode_query(params)
+      params.map do |key, value|
+        "#{escape_component(key)}=#{escape_component(value)}"
+      end.join("&")
+    end
+
+    # Percent-encode a single component the way JavaScript's
+    # `encodeURIComponent` does (spaces become "%20", not "+").
+    #
+    # @param value [#to_s]
+    # @return [String]
+    def escape_component(value)
+      value.to_s.b.gsub(UNRESERVED) { |byte| format("%%%02X", byte.ord) }
+    end
+
+    # Substitute `{name}` placeholders in a template with URL-encoded values
+    # from +params+ (string or symbol keys). Missing keys become empty strings.
+    # Used to build role-specific fallback URLs, e.g.
+    #   "https://example.com/refer?code={code}&role={role}"
+    #
+    # @param template [String]
+    # @param params [Hash]
+    # @return [String]
+    def interpolate(template, params)
+      template.to_s.gsub(/\{(\w+)\}/) do
+        key = Regexp.last_match(1)
+        value = params[key]
+        value = params[key.to_sym] if value.nil? && params.respond_to?(:key?)
+        escape_component(value)
+      end
+    end
+  end
+end

data/lib/linkio/version.rb

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

data/lib/linkio.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "linkio/version"
+require "linkio/errors"
+require "linkio/platform"
+require "linkio/utils"
+require "linkio/pending_link_data"
+require "linkio/referral_data"
+require "linkio/deep_link_data"
+require "linkio/request"
+require "linkio/result"
+require "linkio/app_target"
+require "linkio/configuration"
+require "linkio/storage/base"
+require "linkio/storage/in_memory_storage"
+require "linkio/storage/redis_storage"
+require "linkio/smart_redirect"
+require "linkio/client"
+
+# LinkIO is a self-hosted deep linking backend for mobile apps -
+# an open source alternative to Branch.io.
+#
+# The module also exposes a global configuration/client convenience API used by
+# the Rack middleware and Rails engine:
+#
+#   LinkIO.configure do |config|
+#     config.domain = "example.com"
+#     config.ios_app_id = "123456789"
+#     # ...
+#     config.storage = LinkIO::Storage::InMemoryStorage.new
+#   end
+#
+#   LinkIO.client # => memoized LinkIO::Client
+module LinkIO
+  class << self
+    # @return [LinkIO::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    attr_writer :configuration
+
+    # Configure the global LinkIO instance.
+    #
+    # @yieldparam config [LinkIO::Configuration]
+    # @return [LinkIO::Configuration]
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # A memoized client built from the global configuration.
+    # Reset with {reset!} after changing configuration.
+    #
+    # @return [LinkIO::Client]
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Reset global configuration and client. Primarily useful in tests.
+    #
+    # @return [void]
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end
+
+require "linkio/rack/middleware"
+require "linkio/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: linkio
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nakul Sharma
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: |
+  LinkIO is a self-hosted deep linking solution for mobile applications, an open
+  source alternative to Branch.io. It generates Apple App Site Association and
+  Android assetlinks.json files, performs smart app-or-store redirects, supports
+  fingerprint-based deferred deep linking, and tracks referrals. It ships a
+  framework-agnostic core, a mountable Rails engine, and Rack middleware.
+email:
+- nakul@tecorb.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/linkio/application_controller.rb
+- app/controllers/linkio/deep_links_controller.rb
+- app/controllers/linkio/pending_links_controller.rb
+- app/controllers/linkio/referrals_controller.rb
+- app/controllers/linkio/well_known_controller.rb
+- config/routes.rb
+- lib/generators/linkio/install/install_generator.rb
+- lib/generators/linkio/install/templates/linkio.rb
+- lib/linkio.rb
+- lib/linkio/app_target.rb
+- lib/linkio/client.rb
+- lib/linkio/configuration.rb
+- lib/linkio/deep_link_data.rb
+- lib/linkio/engine.rb
+- lib/linkio/errors.rb
+- lib/linkio/pending_link_data.rb
+- lib/linkio/platform.rb
+- lib/linkio/rack/middleware.rb
+- lib/linkio/referral_data.rb
+- lib/linkio/request.rb
+- lib/linkio/result.rb
+- lib/linkio/smart_redirect.rb
+- lib/linkio/storage/base.rb
+- lib/linkio/storage/in_memory_storage.rb
+- lib/linkio/storage/redis_storage.rb
+- lib/linkio/utils.rb
+- lib/linkio/version.rb
+homepage: https://github.com/pt-nakul-sharma/linkio-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/pt-nakul-sharma/linkio-rails
+  bug_tracker_uri: https://github.com/pt-nakul-sharma/linkio-rails/issues
+  changelog_uri: https://github.com/pt-nakul-sharma/linkio-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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: 4.0.10
+specification_version: 4
+summary: Self-hosted deep linking backend for mobile apps - open source alternative
+  to Branch.io
+test_files: []