linkio 1.0.0

data/lib/linkio/app_target.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # A single app target that LinkIO can route to. A configuration may hold many
+  # of them, keyed by a routing value (e.g. a "role" such as "user" or
+  # "vendor"). Each target carries its own iOS/Android identifiers, schemes,
+  # store URLs, and an optional per-role +fallback_url+.
+  class AppTarget
+    # Fields required for a target to be usable.
+    REQUIRED = %i[ios_app_id ios_team_id ios_bundle_id android_package_name].freeze
+
+    attr_accessor :key,
+                  :ios_app_id,
+                  :ios_team_id,
+                  :ios_bundle_id,
+                  :ios_app_scheme,
+                  :android_package_name,
+                  :android_app_scheme,
+                  :fallback_url
+    attr_reader :android_sha256_fingerprints
+
+    # @param key [String, Symbol] the routing key (role) for this target
+    # @param attributes [Hash] optional attributes to assign
+    def initialize(key, attributes = {})
+      @key = key.to_s
+      @android_sha256_fingerprints = []
+      attributes.each do |name, value|
+        setter = "#{name}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+    end
+
+    def android_sha256_fingerprints=(value)
+      @android_sha256_fingerprints = Array(value)
+    end
+
+    # @return [String] the iOS App Store URL for this target
+    def ios_store_url
+      "https://apps.apple.com/app/id#{ios_app_id}"
+    end
+
+    # @return [String] the Google Play URL for this target
+    def android_store_url
+      "https://play.google.com/store/apps/details?id=#{android_package_name}"
+    end
+
+    # The store URL appropriate for the given platform.
+    #
+    # @param platform [String] a {LinkIO::Platform} value
+    # @return [String]
+    def store_url(platform)
+      platform == Platform::ANDROID ? android_store_url : ios_store_url
+    end
+
+    # The custom URL scheme for the given platform, if any.
+    #
+    # @param platform [String]
+    # @return [String, nil]
+    def scheme_for(platform)
+      platform == Platform::ANDROID ? android_app_scheme : ios_app_scheme
+    end
+
+    # @return [String] the AASA appID, "<teamId>.<bundleId>"
+    def apple_app_id
+      "#{ios_team_id}.#{ios_bundle_id}"
+    end
+
+    # @return [Array<Symbol>] required fields that are missing
+    def missing_fields
+      REQUIRED.select { |field| blank?(public_send(field)) }
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/linkio/client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # The core deep linking engine. Framework-agnostic: it consumes a
+  # {LinkIO::Request} and returns a {LinkIO::Result}, and exposes plain methods
+  # for pending links and referrals. This is the Ruby port of the Node.js
+  # `LinkIO` class.
+  class Client
+    # 7 days, in milliseconds.
+    PENDING_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+    # @return [LinkIO::Configuration]
+    attr_reader :config
+
+    # @param config [LinkIO::Configuration, Hash] a configuration or attributes hash
+    def initialize(config = nil, **attributes)
+      @config =
+        if config.is_a?(Configuration)
+          config
+        elsif config.is_a?(Hash)
+          Configuration.new(config)
+        else
+          Configuration.new(attributes)
+        end
+      @config.validate!
+    end
+
+    # Handle an incoming deep link request. Selects the app target for the
+    # request's role (see {Configuration#role_param}), stores a pending link (by
+    # IP fingerprint, and by device id when present) for deferred deep linking,
+    # then returns the appropriate response for the detected platform.
+    #
+    # On mobile, it renders a smart-redirect page that opens the role's app and
+    # falls back to that role's store (or the role's +fallback_url+ if set). On
+    # web it redirects to the role's +fallback_url+ when configured, otherwise
+    # returns a JSON message.
+    #
+    # @param request [LinkIO::Request]
+    # @return [LinkIO::Result]
+    def handle_deep_link(request)
+      platform = Platform.detect(request.user_agent)
+      params = request.params
+      app = config.app_for(params[config.role_param])
+
+      persist_pending_link(request, params)
+
+      case platform
+      when Platform::IOS, Platform::ANDROID
+        platform_result(app: app, params: params, platform: platform)
+      else
+        web_result(app, params)
+      end
+    end
+
+    # Retrieve (and consume) a pending link by device id.
+    #
+    # @param device_id [String]
+    # @return [LinkIO::DeepLinkData, nil]
+    def pending_link(device_id)
+      data = config.storage.get_pending_link(device_id)
+      return nil if data.nil?
+
+      config.storage.delete_pending_link(device_id)
+      DeepLinkData.new(url: data.url, params: data.params, deferred: true)
+    end
+
+    # Retrieve (and consume) a pending link by client IP fingerprint. Used for
+    # deferred deep linking after app install. Uses IP-only matching so it works
+    # even when the browser and app send different User-Agents.
+    #
+    # @param ip [String]
+    # @param _user_agent [String, nil] accepted for API parity; unused
+    # @return [LinkIO::DeepLinkData, nil]
+    def pending_link_by_fingerprint(ip, _user_agent = nil)
+      fingerprint = Utils.generate_ip_fingerprint(ip)
+      data = config.storage.get_pending_link_by_fingerprint(fingerprint)
+      return nil if data.nil?
+
+      config.storage.delete_pending_link_by_fingerprint(fingerprint)
+      DeepLinkData.new(url: data.url, params: data.params, deferred: true)
+    end
+
+    # Record a referral. The referral code doubles as the referrer id, matching
+    # the Node.js backend.
+    #
+    # @param referral_code [String]
+    # @param referee_id [String]
+    # @param metadata [Hash, nil]
+    # @return [void]
+    def track_referral(referral_code, referee_id, metadata = nil)
+      referral = ReferralData.new(
+        referrer_id: referral_code,
+        referee_id: referee_id,
+        referral_code: referral_code,
+        timestamp: now_ms,
+        metadata: metadata
+      )
+      config.storage.save_referral(referral)
+      nil
+    end
+
+    # @param referrer_id [String]
+    # @return [Array<LinkIO::ReferralData>]
+    def referrals(referrer_id)
+      config.storage.get_referrals_by_referrer(referrer_id)
+    end
+
+    # @param user_id [String]
+    # @return [LinkIO::ReferralData, nil]
+    def referral_for_user(user_id)
+      config.storage.get_referral_by_referee(user_id)
+    end
+
+    # @return [Hash] the apple-app-site-association document (one detail entry
+    #   per configured app target)
+    def apple_app_site_association
+      details = config.apps.values.map do |app|
+        { "appID" => app.apple_app_id, "paths" => ["*"] }
+      end
+
+      { "applinks" => { "apps" => [], "details" => details } }
+    end
+
+    # @return [Array<Hash>] the assetlinks.json document (one entry per
+    #   app-target/fingerprint pair)
+    def asset_links
+      config.apps.values.flat_map do |app|
+        app.android_sha256_fingerprints.map do |fingerprint|
+          {
+            "relation" => ["delegate_permission/common.handle_all_urls"],
+            "target" => {
+              "namespace" => "android_app",
+              "package_name" => app.android_package_name,
+              "sha256_cert_fingerprints" => [fingerprint]
+            }
+          }
+        end
+      end
+    end
+
+    # Serve an /.well-known/* verification file.
+    #
+    # @param path [String] the request path
+    # @return [LinkIO::Result]
+    def well_known(path)
+      case path
+      when "/.well-known/apple-app-site-association"
+        Result.json(apple_app_site_association)
+      when "/.well-known/assetlinks.json"
+        Result.json(asset_links)
+      else
+        Result.new(type: :html, status: 404, body: "Not Found", headers: { "content-type" => "text/plain" })
+      end
+    end
+
+    private
+
+    def persist_pending_link(request, params)
+      pending = PendingLinkData.new(
+        url: request.full_url,
+        params: params,
+        created_at: now_ms,
+        expires_at: now_ms + PENDING_TTL_MS
+      )
+
+      ip_fingerprint = Utils.generate_ip_fingerprint(request.client_ip)
+      config.storage.save_pending_link_by_fingerprint(ip_fingerprint, pending)
+      config.storage.save_pending_link(request.device_id, pending) if present?(request.device_id)
+    end
+
+    def platform_result(app:, params:, platform:)
+      scheme = app.scheme_for(platform)
+      fallback = fallback_target(app, platform, params)
+      return Result.redirect(fallback) if scheme.nil? || scheme.to_s.empty?
+
+      html = SmartRedirect.page(
+        app_scheme: scheme,
+        params: params,
+        store_url: fallback,
+        platform: platform,
+        package_name: app.android_package_name,
+        timeout: config.fallback_timeout
+      )
+      Result.html(html)
+    end
+
+    # For web/desktop visitors: redirect to the role's fallback_url when set,
+    # otherwise return the Node-compatible JSON message.
+    def web_result(app, params)
+      if present?(app.fallback_url)
+        Result.redirect(Utils.interpolate(app.fallback_url, params))
+      else
+        Result.json({ "message" => "Please open this link on your mobile device", "platform" => "web" })
+      end
+    end
+
+    # The destination used when the app is not installed: the role's custom
+    # fallback_url (interpolated) if set, otherwise the role's store URL.
+    def fallback_target(app, platform, params)
+      return Utils.interpolate(app.fallback_url, params) if present?(app.fallback_url)
+
+      app.store_url(platform)
+    end
+
+    def now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end

data/lib/linkio/configuration.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # Configuration for a {LinkIO::Client}.
+  #
+  # Two ways to configure app targets:
+  #
+  # 1. Single app (flat, Node.js-compatible) — set the iOS/Android attributes
+  #    directly and they apply to one default target:
+  #
+  #      config.ios_app_id = "123"
+  #      config.android_package_name = "com.example.app"
+  #
+  # 2. Multiple apps keyed by a routing value (e.g. a "role") — register a
+  #    target per role. The deep link's +role_param+ selects which one to open:
+  #
+  #      config.role_param = "role"     # query/path param used to route (default)
+  #      config.default_role = "user"   # used when the param is missing/unknown
+  #
+  #      config.app "user" do |app|
+  #        app.ios_app_id = "111"
+  #        # ...
+  #      end
+  #      config.app "vendor" do |app|
+  #        app.ios_app_id = "222"
+  #        # ...
+  #      end
+  class Configuration
+    # ms to wait in the smart-redirect page before falling back.
+    DEFAULT_FALLBACK_TIMEOUT = 2500
+    # Key of the implicit target used by the flat single-app API.
+    DEFAULT_APP_KEY = "default"
+    # Default name of the query/path param used to select an app target.
+    DEFAULT_ROLE_PARAM = "role"
+
+    # Attributes proxied to the implicit default {AppTarget} for single-app use.
+    FLAT_ATTRIBUTES = %i[
+      ios_app_id ios_team_id ios_bundle_id ios_app_scheme
+      android_package_name android_app_scheme android_sha256_fingerprints
+      fallback_url
+    ].freeze
+
+    attr_accessor :domain, :default_deep_link_path, :storage, :default_role
+    attr_writer :fallback_timeout, :role_param
+    attr_reader :apps
+
+    # @param attributes [Hash] top-level attributes to assign
+    def initialize(attributes = {})
+      @apps = {}
+      @fallback_timeout = DEFAULT_FALLBACK_TIMEOUT
+      @role_param = DEFAULT_ROLE_PARAM
+      @default_role = nil
+      attributes.each do |name, value|
+        setter = "#{name}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+    end
+
+    # Proxy the flat single-app attributes to the implicit default target.
+    FLAT_ATTRIBUTES.each do |name|
+      define_method(name) { default_app.public_send(name) }
+      define_method("#{name}=") { |value| default_app.public_send("#{name}=", value) }
+    end
+
+    # @return [String] the routing param name (never blank)
+    def role_param
+      value = @role_param.to_s
+      value.empty? ? DEFAULT_ROLE_PARAM : value
+    end
+
+    # @return [Integer]
+    def fallback_timeout
+      @fallback_timeout || DEFAULT_FALLBACK_TIMEOUT
+    end
+
+    # Register or update an app target for a routing key (role).
+    #
+    #   config.app("vendor") { |app| app.ios_app_id = "222" }
+    #   config.app(:user, ios_app_id: "111")
+    #
+    # @param key [String, Symbol]
+    # @param attributes [Hash]
+    # @yieldparam target [AppTarget]
+    # @return [AppTarget]
+    def app(key, attributes = {})
+      target = (@apps[key.to_s] ||= AppTarget.new(key))
+      attributes.each do |name, value|
+        setter = "#{name}="
+        target.public_send(setter, value) if target.respond_to?(setter)
+      end
+      yield target if block_given?
+      target
+    end
+
+    # The implicit target backing the flat single-app API.
+    #
+    # @return [AppTarget]
+    def default_app
+      @apps[DEFAULT_APP_KEY] ||= AppTarget.new(DEFAULT_APP_KEY)
+    end
+
+    # Resolve the app target for a routing value, falling back to the configured
+    # default role, then the implicit default target, then the first registered
+    # target.
+    #
+    # @param role [String, nil]
+    # @return [AppTarget, nil]
+    def app_for(role)
+      key = role.to_s
+      return @apps[key] if !key.empty? && @apps.key?(key)
+
+      default_target
+    end
+
+    # @raise [ConfigurationError] if the configuration is incomplete
+    # @return [self]
+    def validate!
+      raise ConfigurationError, "LinkIO configuration requires a domain" if blank?(domain)
+      raise ConfigurationError, "LinkIO configuration requires storage" if storage.nil?
+
+      unless storage.respond_to?(:save_pending_link)
+        raise ConfigurationError, "storage must implement the LinkIO::Storage::Base interface"
+      end
+
+      raise ConfigurationError, "at least one app target must be configured" if apps.empty?
+
+      apps.each_value { |target| validate_target!(target) }
+      self
+    end
+
+    private
+
+    def default_target
+      key = default_role.to_s
+      return @apps[key] if !key.empty? && @apps.key?(key)
+
+      @apps[DEFAULT_APP_KEY] || @apps.values.first
+    end
+
+    def validate_target!(target)
+      missing = target.missing_fields
+      return if missing.empty?
+
+      raise ConfigurationError,
+            "app target '#{target.key}' is missing required values: #{missing.join(", ")}"
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/linkio/deep_link_data.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # The resolved deep link returned to a client (e.g. an SDK) when it retrieves
+  # a pending link. `deferred` indicates the link was stored before the app was
+  # installed/opened.
+  class DeepLinkData
+    attr_reader :url, :params, :deferred
+
+    # @param url [String]
+    # @param params [Hash]
+    # @param deferred [Boolean]
+    def initialize(url:, params:, deferred: true)
+      @url = url
+      @params = params || {}
+      @deferred = deferred
+    end
+
+    alias deferred? deferred
+
+    # @return [Hash]
+    def to_h
+      {
+        "url" => url,
+        "params" => params,
+        "isDeferred" => deferred
+      }
+    end
+  end
+end

data/lib/linkio/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module LinkIO
+  # Mountable Rails engine that wires the LinkIO endpoints into a Rails app.
+  # Mount it at the domain root so the /.well-known verification files are
+  # served correctly:
+  #
+  #   # config/routes.rb
+  #   mount LinkIO::Engine => "/"
+  #
+  # Configure the global client in an initializer (see the install generator):
+  #
+  #   # config/initializers/linkio.rb
+  #   LinkIO.configure do |config|
+  #     config.domain = "example.com"
+  #     # ...
+  #     config.storage = LinkIO::Storage::InMemoryStorage.new
+  #   end
+  class Engine < ::Rails::Engine
+    isolate_namespace LinkIO
+  end
+end

data/lib/linkio/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # Base error class for all LinkIO errors.
+  class Error < StandardError; end
+
+  # Raised when the configuration is missing required values or is invalid.
+  class ConfigurationError < Error; end
+
+  # Raised when a storage adapter is asked to do something it cannot.
+  class NotImplementedError < Error; end
+end

data/lib/linkio/pending_link_data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # A deep link stored for later retrieval (deferred deep linking).
+  # Timestamps are epoch milliseconds, matching the Node.js backend so that
+  # data is interchangeable between the two implementations.
+  class PendingLinkData
+    attr_reader :url, :params, :created_at, :expires_at
+
+    # @param url [String] the full URL that produced this pending link
+    # @param params [Hash] parsed query/path parameters
+    # @param created_at [Integer] epoch milliseconds
+    # @param expires_at [Integer] epoch milliseconds
+    def initialize(url:, params:, created_at:, expires_at:)
+      @url = url
+      @params = params || {}
+      @created_at = created_at
+      @expires_at = expires_at
+    end
+
+    # @param now_ms [Integer] current time in epoch milliseconds
+    # @return [Boolean]
+    def expired?(now_ms = (Time.now.to_f * 1000).to_i)
+      now_ms > expires_at
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        "url" => url,
+        "params" => params,
+        "createdAt" => created_at,
+        "expiresAt" => expires_at
+      }
+    end
+
+    # Build from a hash using either camelCase (JSON/Node-compatible) or
+    # snake_case keys.
+    #
+    # @param hash [Hash]
+    # @return [PendingLinkData]
+    def self.from_h(hash)
+      h = stringify(hash)
+      new(
+        url: h["url"],
+        params: h["params"] || {},
+        created_at: h["createdAt"] || h["created_at"],
+        expires_at: h["expiresAt"] || h["expires_at"]
+      )
+    end
+
+    def self.stringify(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+    private_class_method :stringify
+  end
+end

data/lib/linkio/platform.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # Platform detection for incoming requests. Mirrors the `Platform` enum from
+  # the Node.js LinkIO backend.
+  module Platform
+    IOS = "ios"
+    ANDROID = "android"
+    WEB = "web"
+    UNKNOWN = "unknown"
+
+    ALL = [IOS, ANDROID, WEB, UNKNOWN].freeze
+
+    IOS_PATTERN = /iphone|ipad|ipod|ios/i
+    ANDROID_PATTERN = /android/i
+
+    module_function
+
+    # Detect the platform from a User-Agent string.
+    #
+    # @param user_agent [String, nil]
+    # @return [String] one of {IOS}, {ANDROID} or {WEB}
+    def detect(user_agent)
+      ua = user_agent.to_s
+      return IOS if ua.match?(IOS_PATTERN)
+      return ANDROID if ua.match?(ANDROID_PATTERN)
+
+      WEB
+    end
+  end
+end