rerout 0.1.0

data/lib/rerout/models.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Plain-old Ruby value objects returned by the Rerout API. Each model is a
+  # frozen struct-like class with `from_hash` for JSON ingestion and value
+  # equality semantics.
+  module Models
+    # A short link.
+    class Link
+      ATTRS = %i[
+        code short_url domain_hostname target_url project_id expires_at
+        is_active seo_title seo_description seo_image_url seo_canonical_url
+        seo_noindex seo_updated_at created_at updated_at
+      ].freeze
+
+      attr_reader(*ATTRS)
+
+      def initialize(**attrs)
+        ATTRS.each { |k| instance_variable_set(:"@#{k}", attrs[k]) }
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          code: hash['code'],
+          short_url: hash['short_url'],
+          domain_hostname: hash['domain_hostname'],
+          target_url: hash['target_url'],
+          project_id: hash['project_id'],
+          expires_at: hash['expires_at'],
+          is_active: hash['is_active'],
+          seo_title: hash['seo_title'],
+          seo_description: hash['seo_description'],
+          seo_image_url: hash['seo_image_url'],
+          seo_canonical_url: hash['seo_canonical_url'],
+          seo_noindex: hash.fetch('seo_noindex', true),
+          seo_updated_at: hash['seo_updated_at'],
+          created_at: hash['created_at'],
+          updated_at: hash['updated_at']
+        )
+      end
+
+      def to_h
+        ATTRS.to_h { |k| [k, public_send(k)] }
+      end
+
+      def ==(other)
+        other.is_a?(Link) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # A breakdown bucket — `{ value: "ZA", clicks: 42 }`.
+    class StatsBreakdown
+      attr_reader :value, :clicks
+
+      def initialize(value:, clicks:)
+        @value = value
+        @clicks = clicks
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(value: hash['value'], clicks: hash['clicks'])
+      end
+
+      def to_h
+        { value: value, clicks: clicks }
+      end
+
+      def ==(other)
+        other.is_a?(StatsBreakdown) && other.value == value && other.clicks == clicks
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, value, clicks].hash
+      end
+    end
+
+    # One day in a `daily` time-series.
+    class DailyClicksPoint
+      attr_reader :day, :clicks, :qr_scans
+
+      def initialize(day:, clicks:, qr_scans:)
+        @day = day
+        @clicks = clicks
+        @qr_scans = qr_scans
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(day: hash['day'], clicks: hash['clicks'], qr_scans: hash['qr_scans'])
+      end
+
+      def to_h
+        { day: day, clicks: clicks, qr_scans: qr_scans }
+      end
+
+      def ==(other)
+        other.is_a?(DailyClicksPoint) && other.day == day &&
+          other.clicks == clicks && other.qr_scans == qr_scans
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, day, clicks, qr_scans].hash
+      end
+    end
+
+    # Per-link click stats response.
+    class LinkStats
+      attr_reader :code, :days, :total_clicks, :qr_scans, :countries, :referrers
+
+      def initialize(code:, days:, total_clicks:, qr_scans:, countries:, referrers:)
+        @code = code
+        @days = days
+        @total_clicks = total_clicks
+        @qr_scans = qr_scans
+        @countries = countries.freeze
+        @referrers = referrers.freeze
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          code: hash['code'],
+          days: hash['days'],
+          total_clicks: hash['total_clicks'],
+          qr_scans: hash['qr_scans'],
+          countries: (hash['countries'] || []).map { |c| StatsBreakdown.from_hash(c) },
+          referrers: (hash['referrers'] || []).map { |c| StatsBreakdown.from_hash(c) }
+        )
+      end
+
+      def to_h
+        {
+          code: code, days: days, total_clicks: total_clicks, qr_scans: qr_scans,
+          countries: countries.map(&:to_h), referrers: referrers.map(&:to_h)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(LinkStats) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # Project-wide aggregate stats response.
+    class ProjectStats
+      attr_reader :days, :total_clicks, :qr_scans, :daily, :countries, :referrers,
+                  :devices, :browsers, :top_codes
+
+      def initialize(**attrs)
+        @days = attrs[:days]
+        @total_clicks = attrs[:total_clicks]
+        @qr_scans = attrs[:qr_scans]
+        @daily = attrs[:daily].freeze
+        @countries = attrs[:countries].freeze
+        @referrers = attrs[:referrers].freeze
+        @devices = attrs[:devices].freeze
+        @browsers = attrs[:browsers].freeze
+        @top_codes = attrs[:top_codes].freeze
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          days: hash['days'],
+          total_clicks: hash['total_clicks'],
+          qr_scans: hash['qr_scans'],
+          daily: (hash['daily'] || []).map { |d| DailyClicksPoint.from_hash(d) },
+          countries: (hash['countries'] || []).map { |b| StatsBreakdown.from_hash(b) },
+          referrers: (hash['referrers'] || []).map { |b| StatsBreakdown.from_hash(b) },
+          devices: (hash['devices'] || []).map { |b| StatsBreakdown.from_hash(b) },
+          browsers: (hash['browsers'] || []).map { |b| StatsBreakdown.from_hash(b) },
+          top_codes: (hash['top_codes'] || []).map { |b| StatsBreakdown.from_hash(b) }
+        )
+      end
+
+      def to_h
+        {
+          days: days, total_clicks: total_clicks, qr_scans: qr_scans,
+          daily: daily.map(&:to_h),
+          countries: countries.map(&:to_h),
+          referrers: referrers.map(&:to_h),
+          devices: devices.map(&:to_h),
+          browsers: browsers.map(&:to_h),
+          top_codes: top_codes.map(&:to_h)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(ProjectStats) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # Paginated list of links.
+    class ListLinksResult
+      attr_reader :links, :next_cursor
+
+      def initialize(links:, next_cursor:)
+        @links = links.freeze
+        @next_cursor = next_cursor
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          links: (hash['links'] || []).map { |l| Link.from_hash(l) },
+          next_cursor: hash['next_cursor']
+        )
+      end
+
+      def to_h
+        { links: links.map(&:to_h), next_cursor: next_cursor }
+      end
+
+      def ==(other)
+        other.is_a?(ListLinksResult) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # Project identity envelope.
+    class Project
+      attr_reader :id, :name, :slug
+
+      def initialize(id:, name:, slug:)
+        @id = id
+        @name = name
+        @slug = slug
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(id: hash['id'], name: hash['name'], slug: hash['slug'])
+      end
+
+      def to_h
+        { id: id, name: name, slug: slug }
+      end
+
+      def ==(other)
+        other.is_a?(Project) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, id, name, slug].hash
+      end
+    end
+  end
+end

data/lib/rerout/project.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rerout
+  module Resources
+    # Project-level operations namespace.
+    class Project
+      # @param client [Rerout::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Aggregate stats across every link in the project. Defaults to 30 days.
+      #
+      # @param days [Integer]
+      # @return [Rerout::Models::ProjectStats]
+      def stats(days: 30)
+        response = @client.request(
+          method: :get,
+          path: '/v1/projects/me/stats',
+          query: { 'days' => days }
+        )
+        Models::ProjectStats.from_hash(response)
+      end
+
+      # Info about the project that owns the current API key.
+      #
+      # @return [Rerout::Models::Project]
+      def me
+        response = @client.request(method: :get, path: '/v1/projects/me')
+        Models::Project.from_hash(response)
+      end
+    end
+  end
+end

data/lib/rerout/qr.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'uri'
+
+module Rerout
+  module Resources
+    # QR helpers.
+    class Qr
+      # @param client [Rerout::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Build the URL the API serves the QR SVG from. Pure — does not hit
+      # the network.
+      #
+      # @param code [String]
+      # @param options [Rerout::QrOptions, Hash, nil]
+      # @return [String]
+      def url(code, options = nil)
+        Qr.build_url(base_url: @client.base_url, code: code, options: options)
+      end
+
+      # Fetch the QR as an SVG string. Attaches the bearer token.
+      #
+      # @param code [String]
+      # @param options [Rerout::QrOptions, Hash, nil]
+      # @return [String] the rendered SVG markup.
+      def svg(code, options = nil)
+        raise ArgumentError, 'code is required' if code.nil? || code.to_s.empty?
+
+        qopts = Qr.coerce_options(options)
+        path = "/v1/links/#{ERB::Util.url_encode(code.to_s)}/qr"
+        @client.request(
+          method: :get,
+          path: path,
+          query: qopts.to_query_hash,
+          raw: true
+        )
+      end
+
+      # @api private — also used by callers that just want a URL without a client.
+      def self.build_url(base_url:, code:, options: nil)
+        raise ArgumentError, 'code is required' if code.nil? || code.to_s.empty?
+
+        qopts = coerce_options(options)
+        base = base_url.to_s.sub(%r{/+\z}, '')
+        path = "/v1/links/#{ERB::Util.url_encode(code.to_s)}/qr"
+        url = "#{base}#{path}"
+        query = qopts.to_query_hash
+        return url if query.empty?
+
+        "#{url}?#{URI.encode_www_form(query)}"
+      end
+
+      # @api private
+      def self.coerce_options(options)
+        case options
+        when nil then QrOptions.new
+        when QrOptions then options
+        when Hash then QrOptions.new(**options.transform_keys(&:to_sym))
+        else
+          raise ArgumentError, 'options must be a Rerout::QrOptions, Hash, or nil'
+        end
+      end
+    end
+  end
+end

data/lib/rerout/qr_options.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Options for the QR endpoint. All fields are optional.
+  #
+  # - `size` (Integer): module size in px (1..32). Server default 8.
+  # - `margin` (Integer): quiet zone in modules (0..16). Server default 4.
+  # - `ecc` (String): error correction level. One of `L`, `M`, `Q`, `H`.
+  # - `domain` (String): force the QR to encode a specific verified custom domain.
+  # - `refresh` (String, true): cache-bust on regenerate. `true` is serialized as `"1"`.
+  class QrOptions
+    attr_reader :size, :margin, :ecc, :domain, :refresh
+
+    ALLOWED_ECC = %w[L M Q H].freeze
+
+    def initialize(size: nil, margin: nil, ecc: nil, domain: nil, refresh: nil)
+      if ecc && !ALLOWED_ECC.include?(ecc.to_s)
+        raise ArgumentError, "ecc must be one of #{ALLOWED_ECC.inspect}, got #{ecc.inspect}"
+      end
+
+      @size = size
+      @margin = margin
+      @ecc = ecc
+      @domain = domain
+      @refresh = refresh
+      freeze
+    end
+
+    # @return [Boolean] true when no field is set.
+    def empty?
+      size.nil? && margin.nil? && ecc.nil? && domain.nil? && refresh.nil?
+    end
+
+    # Serialize options as a `{ key => string }` hash ready to be turned into
+    # a query string. `refresh: true` becomes `"1"`.
+    def to_query_hash
+      out = {}
+      out['size'] = size.to_s unless size.nil?
+      out['margin'] = margin.to_s unless margin.nil?
+      out['ecc'] = ecc.to_s unless ecc.nil?
+      out['domain'] = domain.to_s unless domain.nil?
+      unless refresh.nil?
+        out['refresh'] = refresh == true ? '1' : refresh.to_s
+      end
+      out
+    end
+  end
+end

data/lib/rerout/update_link_input.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Sentinel singleton used to distinguish "leave the field alone" (not passed,
+  # default `Rerout::OMIT`) from "set the field to null on the server"
+  # (`Rerout::CLEAR`).
+  module ClearSentinel
+    def self.inspect
+      'Rerout::CLEAR'
+    end
+  end
+
+  # @api private — internal default sentinel meaning "field not passed".
+  module OmitSentinel
+    def self.inspect
+      'Rerout::OMIT'
+    end
+  end
+
+  # Public sentinel — pass `Rerout::CLEAR` to a nullable field on
+  # {Rerout::UpdateLinkInput} to send `null` on the wire.
+  #
+  # @example
+  #   Rerout::UpdateLinkInput.new(seo_title: Rerout::CLEAR)
+  CLEAR = ClearSentinel
+  # Internal default — distinguishes "not provided" from "set to nil".
+  OMIT = OmitSentinel
+
+  # Request body for `PATCH /v1/links/:code`. Every field is optional. To
+  # send `null` to the server (clear an existing value), pass `Rerout::CLEAR`
+  # to that keyword argument.
+  #
+  # @example
+  #   Rerout::UpdateLinkInput.new(target_url: 'https://new.example.com')
+  #   Rerout::UpdateLinkInput.new(expires_at: Rerout::CLEAR)
+  class UpdateLinkInput
+    FIELDS = %i[
+      target_url expires_at is_active seo_title seo_description
+      seo_image_url seo_canonical_url seo_noindex
+    ].freeze
+
+    def initialize(target_url: OMIT, expires_at: OMIT, is_active: OMIT,
+                   seo_title: OMIT, seo_description: OMIT, seo_image_url: OMIT,
+                   seo_canonical_url: OMIT, seo_noindex: OMIT)
+      @values = {
+        target_url: target_url,
+        expires_at: expires_at,
+        is_active: is_active,
+        seo_title: seo_title,
+        seo_description: seo_description,
+        seo_image_url: seo_image_url,
+        seo_canonical_url: seo_canonical_url,
+        seo_noindex: seo_noindex
+      }
+      freeze
+    end
+
+    # Serialize for the wire. Unset fields are omitted; `Rerout::CLEAR`
+    # becomes `null`.
+    def to_h
+      out = {}
+      FIELDS.each do |field|
+        v = @values[field]
+        next if v.equal?(OMIT)
+
+        out[field.to_s] = v.equal?(CLEAR) ? nil : v
+      end
+      out
+    end
+
+    # @return [Boolean] true when no field was set.
+    def empty?
+      to_h.empty?
+    end
+
+    # @return [Object] the raw value (sentinel or actual) for a field.
+    def value_for(field)
+      @values.fetch(field)
+    end
+  end
+end

data/lib/rerout/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Library version. Follows semantic versioning.
+  VERSION = '0.1.0'
+end

data/lib/rerout/webhooks.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Rerout
+  # Webhook signature verification.
+  #
+  # Rerout signs every webhook delivery with an `X-Rerout-Signature` header
+  # shaped as `t={unix_seconds},v1={hex_hmac_sha256}`. The HMAC is computed
+  # over `"{timestamp}.{raw_body}"` with the endpoint signing secret
+  # (`whsec_…`) as the key.
+  #
+  # @example Rack / Rails controller
+  #   raw = request.body.read
+  #   ok = Rerout::Webhooks.verify_signature(
+  #     raw_body: raw,
+  #     signature_header: request.headers['X-Rerout-Signature'],
+  #     secret: ENV.fetch('REROUT_WEBHOOK_SECRET')
+  #   )
+  #   head(:unauthorized) and return unless ok
+  module Webhooks
+    # Default tolerance window in seconds between the `t=` timestamp and the
+    # current time. Five minutes — protects against captured-replay attacks.
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    # Verify a Rerout webhook signature.
+    #
+    # Returns `true` only when the header parses cleanly, the timestamp is
+    # within `tolerance_seconds` of `now`, and the computed HMAC matches the
+    # supplied `v1` in constant time. Returns `false` for every failure mode —
+    # it never raises.
+    #
+    # @param raw_body [String] the exact, unmodified request body bytes.
+    # @param signature_header [String] value of the `X-Rerout-Signature` header.
+    # @param secret [String] the endpoint signing secret (`whsec_…`).
+    # @param tolerance_seconds [Integer] staleness window. `0` disables the
+    #   timestamp check entirely. Defaults to 300.
+    # @param now [Proc, #call, nil] injectable clock returning the current
+    #   unix time in seconds. Defaults to `Time.now.to_i`. Useful for tests.
+    # @return [Boolean]
+    def self.verify_signature(raw_body:, signature_header:, secret:,
+                              tolerance_seconds: DEFAULT_TOLERANCE_SECONDS,
+                              now: nil)
+      return false if raw_body.nil?
+      return false if signature_header.nil? || signature_header.to_s.empty?
+      return false if secret.nil? || secret.to_s.empty?
+
+      parsed = parse_header(signature_header.to_s)
+      return false if parsed.nil?
+
+      timestamp, v1 = parsed
+      return false unless within_tolerance?(timestamp, tolerance_seconds, now)
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, "#{timestamp}.#{raw_body}")
+      secure_compare(expected, v1)
+    end
+
+    # Parse `t=<unix>,v1=<hex>` (case-insensitive keys). Returns
+    # `[timestamp, v1]` or `nil` when the header is unusable.
+    #
+    # @api private
+    def self.parse_header(header)
+      timestamp = nil
+      v1 = nil
+      header.split(',').each do |segment|
+        eq = segment.index('=')
+        next if eq.nil? || eq.zero?
+
+        key = segment[0...eq].strip.downcase
+        value = segment[(eq + 1)..].strip
+        case key
+        when 't'
+          parsed = parse_timestamp(value)
+          timestamp = parsed unless parsed.nil?
+        when 'v1'
+          v1 = value unless value.empty?
+        end
+      end
+      return nil if timestamp.nil? || v1.nil?
+
+      [timestamp, v1]
+    end
+    private_class_method :parse_header
+
+    # Strict positive-integer parse — rejects `"abc"`, `"12x"`, `""`, `"-5"`.
+    #
+    # @api private
+    def self.parse_timestamp(value)
+      return nil unless value.match?(/\A\d+\z/)
+
+      parsed = value.to_i
+      parsed.positive? ? parsed : nil
+    end
+    private_class_method :parse_timestamp
+
+    # @api private
+    def self.within_tolerance?(timestamp, tolerance_seconds, now)
+      return true if tolerance_seconds.to_i <= 0
+
+      current = now ? now.call.to_i : Time.now.to_i
+      (current - timestamp).abs <= tolerance_seconds.to_i
+    end
+    private_class_method :within_tolerance?
+
+    # Constant-time string comparison over hex strings. Rejects non-hex or
+    # odd-length `v1` values before comparing.
+    #
+    # @api private
+    def self.secure_compare(expected, actual)
+      return false if actual.nil? || actual.empty?
+      return false unless actual.length.even?
+      return false unless actual.match?(/\A[0-9a-fA-F]+\z/)
+      return false unless expected.bytesize == actual.bytesize
+
+      OpenSSL.fixed_length_secure_compare(
+        expected.downcase, actual.downcase
+      )
+    rescue StandardError
+      false
+    end
+    private_class_method :secure_compare
+  end
+
+  # Module-level convenience matching the BRIEF's free-function shape.
+  #
+  # @see Rerout::Webhooks.verify_signature
+  # @return [Boolean]
+  def self.verify_signature(raw_body:, signature_header:, secret:,
+                            tolerance_seconds: Webhooks::DEFAULT_TOLERANCE_SECONDS,
+                            now: nil)
+    Webhooks.verify_signature(
+      raw_body: raw_body,
+      signature_header: signature_header,
+      secret: secret,
+      tolerance_seconds: tolerance_seconds,
+      now: now
+    )
+  end
+end

data/lib/rerout.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'rerout/version'
+require_relative 'rerout/error'
+require_relative 'rerout/models'
+require_relative 'rerout/create_link_input'
+require_relative 'rerout/update_link_input'
+require_relative 'rerout/qr_options'
+require_relative 'rerout/webhooks'
+require_relative 'rerout/links'
+require_relative 'rerout/project'
+require_relative 'rerout/qr'
+require_relative 'rerout/client'
+
+# Official Ruby SDK for the Rerout branded-link API.
+#
+# Branded link infrastructure on Cloudflare — create short links, render QR
+# codes, read analytics, and verify webhook signatures.
+#
+# @example Hello world
+#   require 'rerout'
+#
+#   rerout = Rerout::Client.new(api_key: ENV.fetch('REROUT_API_KEY'))
+#   link = rerout.links.create(
+#     Rerout::CreateLinkInput.new(target_url: 'https://example.com/sale')
+#   )
+#   puts link.short_url
+#
+# @see https://rerout.co
+# @see https://github.com/ModestNerds-Co/rerout-sdks
+module Rerout
+end