linkio 1.0.0

data/lib/linkio/rack/middleware.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LinkIO
+  module Rack
+    # Rack middleware that serves the LinkIO endpoints without any framework.
+    # Mount it in a config.ru or any Rack app:
+    #
+    #   use LinkIO::Rack::Middleware, client: my_client
+    #   run MyApp
+    #
+    # Requests it does not recognise are passed through to the wrapped app.
+    # Handled routes:
+    #   GET  /.well-known/apple-app-site-association
+    #   GET  /.well-known/assetlinks.json
+    #   GET  /link
+    #   GET  /pending-link
+    #   GET  /pending-link/:device_id
+    #   POST /track-referral
+    #   GET  /referrals/:referrer_id
+    class Middleware
+      # @param app [#call] the downstream Rack app
+      # @param client [LinkIO::Client] defaults to the global {LinkIO.client}
+      def initialize(app, client: nil)
+        @app = app
+        @client = client
+      end
+
+      def call(env)
+        request = ::Rack::Request.new(env) if defined?(::Rack::Request)
+        method = env["REQUEST_METHOD"]
+        path = env["PATH_INFO"].to_s
+
+        result = route(method, path, env, request)
+        result ? result.to_rack : @app.call(env)
+      end
+
+      private
+
+      def client
+        @client || LinkIO.client
+      end
+
+      def route(method, path, env, request)
+        return client.well_known(path) if path.start_with?("/.well-known/")
+
+        case method
+        when "GET"
+          get_routes(path, env)
+        when "POST"
+          post_routes(path, request, env)
+        end
+      end
+
+      def get_routes(path, env)
+        if path == "/link"
+          client.handle_deep_link(Request.from_rack(env))
+        elsif path == "/pending-link"
+          fingerprint_pending_link(env)
+        elsif (device_id = capture(path, %r{\A/pending-link/(.+)\z}))
+          not_found_or(client.pending_link(device_id))
+        elsif (referrer_id = capture(path, %r{\A/referrals/(.+)\z}))
+          Result.json({ "referrals" => client.referrals(referrer_id).map(&:to_h) })
+        end
+      end
+
+      def post_routes(path, request, _env)
+        return unless path == "/track-referral"
+
+        body = parse_body(request)
+        client.track_referral(body["referralCode"], body["userId"], body["metadata"])
+        Result.json({ "success" => true })
+      end
+
+      def fingerprint_pending_link(env)
+        ip = Utils.client_ip(
+          forwarded_for: env["HTTP_X_FORWARDED_FOR"],
+          remote_address: env["REMOTE_ADDR"]
+        )
+        not_found_or(client.pending_link_by_fingerprint(ip, env["HTTP_USER_AGENT"]))
+      end
+
+      def not_found_or(deep_link)
+        return Result.json({ "error" => "No pending link found" }, status: 404) if deep_link.nil?
+
+        Result.json(deep_link.to_h)
+      end
+
+      def capture(path, regex)
+        match = regex.match(path)
+        match && match[1]
+      end
+
+      def parse_body(request)
+        raw = request&.body&.read.to_s
+        return {} if raw.empty?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/linkio/referral_data.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # A referral relationship between a referrer and a referee.
+  # `timestamp` is epoch milliseconds, matching the Node.js backend.
+  class ReferralData
+    attr_reader :referrer_id, :referee_id, :referral_code, :timestamp, :metadata
+
+    # @param referrer_id [String]
+    # @param referee_id [String]
+    # @param referral_code [String]
+    # @param timestamp [Integer] epoch milliseconds
+    # @param metadata [Hash, nil]
+    def initialize(referrer_id:, referee_id:, referral_code:, timestamp:, metadata: nil)
+      @referrer_id = referrer_id
+      @referee_id = referee_id
+      @referral_code = referral_code
+      @timestamp = timestamp
+      @metadata = metadata
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        "referrerId" => referrer_id,
+        "refereeId" => referee_id,
+        "referralCode" => referral_code,
+        "timestamp" => timestamp,
+        "metadata" => metadata
+      }
+    end
+
+    # Build from a hash using either camelCase or snake_case keys.
+    #
+    # @param hash [Hash]
+    # @return [ReferralData]
+    def self.from_h(hash)
+      h = hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      new(
+        referrer_id: h["referrerId"] || h["referrer_id"],
+        referee_id: h["refereeId"] || h["referee_id"],
+        referral_code: h["referralCode"] || h["referral_code"],
+        timestamp: h["timestamp"],
+        metadata: h["metadata"]
+      )
+    end
+  end
+end

data/lib/linkio/request.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # A framework-agnostic view of an incoming HTTP request, containing only what
+  # {LinkIO::Client#handle_deep_link} needs. Build one directly, from a Rack
+  # env with {from_rack}, or let the Rails engine construct it for you.
+  class Request
+    attr_reader :user_agent, :full_url, :query_params, :path_params, :client_ip, :device_id
+
+    # @param user_agent [String, nil]
+    # @param full_url [String] absolute request URL including query string
+    # @param query_params [Hash] parsed query parameters
+    # @param path_params [Hash] route/path parameters to merge into params
+    # @param client_ip [String] resolved client IP (proxy-aware)
+    # @param device_id [String, nil] explicit device id (query "deviceId" or X-Device-Id)
+    def initialize(full_url:, client_ip:, user_agent: nil, query_params: {}, path_params: {}, device_id: nil)
+      @user_agent = user_agent.to_s
+      @full_url = full_url
+      @query_params = stringify(query_params)
+      @path_params = stringify(path_params)
+      @client_ip = client_ip
+      @device_id = device_id
+    end
+
+    # Merged query + path params (path params win), matching the Node backend's
+    # behaviour of overlaying `req.params` onto the parsed query params.
+    #
+    # @return [Hash{String => Object}]
+    def params
+      merged = query_params.dup
+      path_params.each { |k, v| merged[k] = v unless v.nil? || v.to_s.empty? }
+      merged
+    end
+
+    # Build a Request from a Rack environment hash.
+    #
+    # @param env [Hash] a Rack env
+    # @param path_params [Hash] optional route params (e.g. from a router)
+    # @return [LinkIO::Request]
+    def self.from_rack(env, path_params: {})
+      user_agent = env["HTTP_USER_AGENT"]
+      full_url = rack_full_url(env)
+      query = Utils.parse_query_params(full_url)
+      ip = Utils.client_ip(
+        forwarded_for: env["HTTP_X_FORWARDED_FOR"],
+        remote_address: env["REMOTE_ADDR"]
+      )
+      device_id = query["deviceId"] || env["HTTP_X_DEVICE_ID"]
+
+      new(
+        user_agent: user_agent,
+        full_url: full_url,
+        query_params: query,
+        path_params: path_params,
+        client_ip: ip,
+        device_id: device_id
+      )
+    end
+
+    def self.rack_full_url(env)
+      scheme = env["rack.url_scheme"] || "http"
+      host = env["HTTP_HOST"] || env["SERVER_NAME"] || "localhost"
+      path = env["PATH_INFO"].to_s
+      query = env["QUERY_STRING"].to_s
+      url = "#{scheme}://#{host}#{path}"
+      query.empty? ? url : "#{url}?#{query}"
+    end
+    private_class_method :rack_full_url
+
+    private
+
+    def stringify(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+  end
+end

data/lib/linkio/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LinkIO
+  # A framework-agnostic description of the response the caller should send.
+  # {LinkIO::Client} returns these so that the same logic can be wired into
+  # Rack, Rails, Sinatra, or anything else.
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] one of :redirect, :html, :json
+  class Result
+    # Header names are lowercase to satisfy Rack 3's strict lint (Rack 2 and
+    # Rails accept them too).
+    HTML_HEADERS = { "content-type" => "text/html; charset=utf-8" }.freeze
+    JSON_HEADERS = { "content-type" => "application/json; charset=utf-8" }.freeze
+
+    attr_reader :type, :status, :body, :headers
+
+    def initialize(type:, status:, body:, headers: {})
+      @type = type
+      @status = status
+      @body = body
+      @headers = headers
+    end
+
+    # @return [Result] a 302 redirect to +url+
+    def self.redirect(url, status: 302)
+      new(type: :redirect, status: status, body: url, headers: { "location" => url })
+    end
+
+    # @return [Result] an HTML response
+    def self.html(body, status: 200)
+      new(type: :html, status: status, body: body, headers: HTML_HEADERS.dup)
+    end
+
+    # @param object [Object] serialized to JSON for the body
+    # @return [Result] a JSON response (body kept as the raw object too)
+    def self.json(object, status: 200)
+      new(type: :json, status: status, body: object, headers: JSON_HEADERS.dup)
+    end
+
+    def redirect?
+      type == :redirect
+    end
+
+    def html?
+      type == :html
+    end
+
+    def json?
+      type == :json
+    end
+
+    # The location for redirect results.
+    # @return [String, nil]
+    def location
+      headers["location"]
+    end
+
+    # The response body as a string, JSON-encoding json results.
+    # @return [String]
+    def body_string
+      json? ? JSON.generate(body) : body.to_s
+    end
+
+    # Convert to a standard Rack response triple.
+    #
+    # @return [Array(Integer, Hash, Array<String>)]
+    def to_rack
+      [status, headers.dup, [body_string]]
+    end
+  end
+end

data/lib/linkio/smart_redirect.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module LinkIO
+  # Generates the HTML page that attempts to open the native app via its custom
+  # scheme and falls back to the app store after a timeout. This is a faithful
+  # port of the Node.js backend's `generateSmartRedirectPage`.
+  module SmartRedirect
+    module_function
+
+    # @param app_scheme [String] e.g. "rokart"
+    # @param params [Hash] parameters forwarded to the app link
+    # @param store_url [String] fallback store URL
+    # @param platform [String] {LinkIO::Platform} value
+    # @param package_name [String] Android package name (for the intent:// fallback)
+    # @param timeout [Integer] ms before falling back to the store
+    # @return [String] a complete HTML document
+    def page(app_scheme:, params:, store_url:, platform:, package_name:, timeout:)
+      query_string = Utils.encode_query(params)
+      app_uri = "#{app_scheme}://link#{"?#{query_string}" unless query_string.empty?}"
+
+      android_intent =
+        if platform == Platform::ANDROID
+          "intent://link#{"?#{query_string}" unless query_string.empty?}" \
+            "#Intent;scheme=#{app_scheme};package=#{package_name};end"
+        else
+          ""
+        end
+
+      is_android = platform == Platform::ANDROID
+
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>Opening App...</title>
+          <style>
+            body {
+              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+              display: flex;
+              justify-content: center;
+              align-items: center;
+              min-height: 100vh;
+              margin: 0;
+              background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+              color: white;
+              text-align: center;
+            }
+            .container { padding: 20px; }
+            .spinner {
+              width: 50px;
+              height: 50px;
+              border: 3px solid rgba(255,255,255,0.3);
+              border-radius: 50%;
+              border-top-color: white;
+              animation: spin 1s linear infinite;
+              margin: 0 auto 20px;
+            }
+            @keyframes spin { to { transform: rotate(360deg); } }
+            h1 { font-size: 24px; margin-bottom: 10px; }
+            p { opacity: 0.9; margin-bottom: 20px; }
+            .btn {
+              display: inline-block;
+              padding: 12px 24px;
+              background: white;
+              color: #667eea;
+              text-decoration: none;
+              border-radius: 8px;
+              font-weight: 600;
+              margin: 5px;
+            }
+          </style>
+        </head>
+        <body>
+          <div class="container">
+            <div class="spinner"></div>
+            <h1>Opening App...</h1>
+            <p>If the app doesn't open, tap below to download</p>
+            <a href="#{store_url}" class="btn">Download App</a>
+          </div>
+          <script>
+            (function() {
+              var appUri = "#{app_uri}";
+              var storeUrl = "#{store_url}";
+              var timeout = #{timeout};
+              var androidIntent = "#{android_intent}";
+              var isAndroid = #{is_android};
+
+              var startTime = Date.now();
+              var hasFocus = true;
+
+              // Track if user leaves the page (app opened)
+              window.addEventListener('blur', function() { hasFocus = false; });
+              window.addEventListener('pagehide', function() { hasFocus = false; });
+              document.addEventListener('visibilitychange', function() {
+                if (document.hidden) hasFocus = false;
+              });
+
+              // Try to open app
+              var iframe = document.createElement('iframe');
+              iframe.style.display = 'none';
+              iframe.src = appUri;
+              document.body.appendChild(iframe);
+
+              // Also try direct location for some browsers
+              setTimeout(function() {
+                if (hasFocus) {
+                  window.location.href = appUri;
+                }
+              }, 100);
+
+              // Android: try intent scheme as fallback
+              if (isAndroid && androidIntent) {
+                setTimeout(function() {
+                  if (hasFocus && Date.now() - startTime < timeout) {
+                    window.location.href = androidIntent;
+                  }
+                }, 500);
+              }
+
+              // Fallback to store after timeout
+              setTimeout(function() {
+                if (hasFocus && Date.now() - startTime >= timeout - 100) {
+                  window.location.href = storeUrl;
+                }
+              }, timeout);
+            })();
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+  end
+end

data/lib/linkio/storage/base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module LinkIO
+  module Storage
+    # The storage interface every adapter must implement. Mirrors the
+    # `LinkIOStorage` interface from the Node.js backend. Subclass this (or
+    # duck-type it) to plug in your own backing store.
+    #
+    # All pending-link methods deal in {LinkIO::PendingLinkData}; referral
+    # methods deal in {LinkIO::ReferralData}.
+    class Base
+      # @param device_id [String]
+      # @param data [PendingLinkData]
+      # @return [void]
+      def save_pending_link(device_id, data)
+        raise NotImplementedError, "#{self.class}#save_pending_link is not implemented"
+      end
+
+      # @param device_id [String]
+      # @return [PendingLinkData, nil]
+      def get_pending_link(device_id)
+        raise NotImplementedError, "#{self.class}#get_pending_link is not implemented"
+      end
+
+      # @param device_id [String]
+      # @return [void]
+      def delete_pending_link(device_id)
+        raise NotImplementedError, "#{self.class}#delete_pending_link is not implemented"
+      end
+
+      # @param fingerprint [String]
+      # @param data [PendingLinkData]
+      # @return [void]
+      def save_pending_link_by_fingerprint(fingerprint, data)
+        raise NotImplementedError, "#{self.class}#save_pending_link_by_fingerprint is not implemented"
+      end
+
+      # @param fingerprint [String]
+      # @return [PendingLinkData, nil]
+      def get_pending_link_by_fingerprint(fingerprint)
+        raise NotImplementedError, "#{self.class}#get_pending_link_by_fingerprint is not implemented"
+      end
+
+      # @param fingerprint [String]
+      # @return [void]
+      def delete_pending_link_by_fingerprint(fingerprint)
+        raise NotImplementedError, "#{self.class}#delete_pending_link_by_fingerprint is not implemented"
+      end
+
+      # @param referral [ReferralData]
+      # @return [void]
+      def save_referral(referral)
+        raise NotImplementedError, "#{self.class}#save_referral is not implemented"
+      end
+
+      # @param referrer_id [String]
+      # @return [Array<ReferralData>]
+      def get_referrals_by_referrer(referrer_id)
+        raise NotImplementedError, "#{self.class}#get_referrals_by_referrer is not implemented"
+      end
+
+      # @param referee_id [String]
+      # @return [ReferralData, nil]
+      def get_referral_by_referee(referee_id)
+        raise NotImplementedError, "#{self.class}#get_referral_by_referee is not implemented"
+      end
+    end
+  end
+end

data/lib/linkio/storage/in_memory_storage.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module LinkIO
+  module Storage
+    # A process-local, thread-safe in-memory store. Great for development and
+    # tests. Data is lost when the process exits and is not shared between
+    # processes, so do not use it in production with multiple workers.
+    #
+    # Expiry is enforced lazily on read (matching the Node.js backend).
+    class InMemoryStorage < Base
+      def initialize
+        super
+        @pending_links = {}
+        @fingerprint_links = {}
+        @referrals = []
+        @mutex = Mutex.new
+      end
+
+      def save_pending_link(device_id, data)
+        @mutex.synchronize { @pending_links[device_id] = data }
+        nil
+      end
+
+      def get_pending_link(device_id)
+        @mutex.synchronize { fetch_unexpired(@pending_links, device_id) }
+      end
+
+      def delete_pending_link(device_id)
+        @mutex.synchronize { @pending_links.delete(device_id) }
+        nil
+      end
+
+      def save_pending_link_by_fingerprint(fingerprint, data)
+        @mutex.synchronize { @fingerprint_links[fingerprint] = data }
+        nil
+      end
+
+      def get_pending_link_by_fingerprint(fingerprint)
+        @mutex.synchronize { fetch_unexpired(@fingerprint_links, fingerprint) }
+      end
+
+      def delete_pending_link_by_fingerprint(fingerprint)
+        @mutex.synchronize { @fingerprint_links.delete(fingerprint) }
+        nil
+      end
+
+      def save_referral(referral)
+        @mutex.synchronize do
+          exists = @referrals.any? { |r| r.referee_id == referral.referee_id }
+          @referrals << referral unless exists
+        end
+        nil
+      end
+
+      def get_referrals_by_referrer(referrer_id)
+        @mutex.synchronize { @referrals.select { |r| r.referrer_id == referrer_id } }
+      end
+
+      def get_referral_by_referee(referee_id)
+        @mutex.synchronize { @referrals.find { |r| r.referee_id == referee_id } }
+      end
+
+      private
+
+      # Caller must hold the mutex.
+      def fetch_unexpired(store, key)
+        data = store[key]
+        return nil if data.nil?
+
+        if data.expired?
+          store.delete(key)
+          return nil
+        end
+
+        data
+      end
+    end
+  end
+end

data/lib/linkio/storage/redis_storage.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LinkIO
+  module Storage
+    # A Redis-backed store suitable for production. Pass any client that
+    # responds to the standard `redis` gem methods (`get`, `set`, `del`).
+    # Pending links are written with a TTL so they expire automatically.
+    #
+    #   require "redis"
+    #   storage = LinkIO::Storage::RedisStorage.new(Redis.new)
+    #
+    # Keys are namespaced identically to the Node.js backend
+    # (`linkio:pending:*`, `linkio:fingerprint:*`, `linkio:referral:*`,
+    # `linkio:referrer:*`) so the two implementations can share a Redis.
+    class RedisStorage < Base
+      PENDING_PREFIX = "linkio:pending:"
+      FINGERPRINT_PREFIX = "linkio:fingerprint:"
+      REFERRAL_PREFIX = "linkio:referral:"
+      REFERRER_PREFIX = "linkio:referrer:"
+
+      # @param redis [Object] a redis client (e.g. `Redis.new`)
+      def initialize(redis)
+        super()
+        @redis = redis
+      end
+
+      def save_pending_link(device_id, data)
+        write_pending("#{PENDING_PREFIX}#{device_id}", data)
+      end
+
+      def get_pending_link(device_id)
+        read_pending("#{PENDING_PREFIX}#{device_id}")
+      end
+
+      def delete_pending_link(device_id)
+        @redis.del("#{PENDING_PREFIX}#{device_id}")
+        nil
+      end
+
+      def save_pending_link_by_fingerprint(fingerprint, data)
+        write_pending("#{FINGERPRINT_PREFIX}#{fingerprint}", data)
+      end
+
+      def get_pending_link_by_fingerprint(fingerprint)
+        read_pending("#{FINGERPRINT_PREFIX}#{fingerprint}")
+      end
+
+      def delete_pending_link_by_fingerprint(fingerprint)
+        @redis.del("#{FINGERPRINT_PREFIX}#{fingerprint}")
+        nil
+      end
+
+      def save_referral(referral)
+        return if get_referral_by_referee(referral.referee_id)
+
+        @redis.set("#{REFERRAL_PREFIX}#{referral.referee_id}", JSON.generate(referral.to_h))
+
+        referrer_key = "#{REFERRER_PREFIX}#{referral.referrer_id}"
+        list = read_json(referrer_key) || []
+        list << referral.referee_id
+        @redis.set(referrer_key, JSON.generate(list))
+        nil
+      end
+
+      def get_referrals_by_referrer(referrer_id)
+        referee_ids = read_json("#{REFERRER_PREFIX}#{referrer_id}") || []
+        referee_ids.map do |referee_id|
+          raw = @redis.get("#{REFERRAL_PREFIX}#{referee_id}")
+          raw && ReferralData.from_h(JSON.parse(raw))
+        end.compact
+      end
+
+      def get_referral_by_referee(referee_id)
+        raw = @redis.get("#{REFERRAL_PREFIX}#{referee_id}")
+        raw ? ReferralData.from_h(JSON.parse(raw)) : nil
+      end
+
+      private
+
+      def write_pending(key, data)
+        ttl = ((data.expires_at - (Time.now.to_f * 1000)) / 1000).floor
+        if ttl.positive?
+          @redis.set(key, JSON.generate(data.to_h), ex: ttl)
+        else
+          @redis.set(key, JSON.generate(data.to_h))
+        end
+        nil
+      end
+
+      def read_pending(key)
+        raw = @redis.get(key)
+        return nil if raw.nil?
+
+        data = PendingLinkData.from_h(JSON.parse(raw))
+        if data.expired?
+          @redis.del(key)
+          return nil
+        end
+        data
+      end
+
+      def read_json(key)
+        raw = @redis.get(key)
+        raw ? JSON.parse(raw) : nil
+      end
+    end
+  end
+end