rerout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f45e9af9b2dfce2933563d97fc0adca857d4cdca00a09fdafe89240fcdc1671f
+  data.tar.gz: ed1bbdcea909d9be88f5af98fccfcf4090de2ce1d3f30fb060ee81bc091f6369
+SHA512:
+  metadata.gz: 974f74ad677142b918c0d9c367a785f6c2ae6198122ebaf75ee7d6f55e2b698883cbb01636f976d838bec3346cd96bc02e6da7b36da6adf92f49985feeb09650
+  data.tar.gz: cdc59d4419f34a6e92ccc0765c6aeb03a773c1776bf966a8858bbfc11ea584a5349fdc16e0018fcf7f6aab6dbec93ce250de36dfab849f3f644561ecd1baaa77

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to the `rerout` gem are documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-20
+
+### Added
+
+- Initial public release.
+- `Rerout::Client` with `links`, `project`, and `qr` namespaces and an
+  injectable Faraday connection for tests and edge deployments.
+- Link operations: `create`, `list`, `get`, `update`, `delete`, `stats`.
+- Project operations: `stats`, `me`.
+- QR helpers: pure URL builder (`qr.url`) and authenticated SVG fetch
+  (`qr.svg`).
+- `Rerout::CreateLinkInput` and `Rerout::UpdateLinkInput` request bodies, with
+  the `Rerout::CLEAR` sentinel to distinguish "leave alone" from "set null".
+- `Rerout::QrOptions` with `ecc` validation and `refresh` coercion.
+- Frozen value models: `Link`, `LinkStats`, `ProjectStats`, `DailyClicksPoint`,
+  `StatsBreakdown`, `ListLinksResult`, `Project`.
+- `Rerout::Webhooks.verify_signature` (and the `Rerout.verify_signature`
+  shortcut) — HMAC-SHA256 webhook signature verification with configurable
+  timestamp tolerance and constant-time comparison.
+- `Rerout::Error` with stable `code`, `status`, `path`, `timestamp`, `details`
+  plus `rate_limited?` and `server_error?` convenience flags.
+
+[0.1.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/ruby-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codecraft Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# rerout
+
+Official Ruby SDK for the [Rerout](https://rerout.co) API.
+
+Branded link infrastructure on Cloudflare — create short links, render QR
+codes, read analytics, and verify webhook signatures.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'rerout'
+```
+
+Then run `bundle install`. Or install it directly:
+
+```bash
+gem install rerout
+```
+
+Requires Ruby 3.0+. Built on [Faraday](https://lostisland.github.io/faraday/)
+2.x — the HTTP connection is injectable, so the same client runs against the
+real API in production and a stubbed adapter in tests.
+
+## Usage
+
+```ruby
+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/q4-sale',
+    domain_hostname: 'go.brand.com',
+    code: 'q4'
+  )
+)
+
+puts link.short_url # => https://go.brand.com/q4
+```
+
+## Construction
+
+```ruby
+# Production — only the API key is required.
+rerout = Rerout::Client.new(api_key: ENV.fetch('REROUT_API_KEY'))
+
+# Staging / self-hosted — override the base URL (trailing slashes are trimmed).
+rerout = Rerout::Client.new(
+  api_key: ENV.fetch('REROUT_API_KEY'),
+  base_url: 'https://staging.rerout.co'
+)
+
+# Custom timeout (seconds), User-Agent, or a shared Faraday connection.
+rerout = Rerout::Client.new(
+  api_key: ENV.fetch('REROUT_API_KEY'),
+  timeout: 10,
+  user_agent: 'my-app/2.1'
+)
+```
+
+A blank or missing `api_key` raises `Rerout::Error` with code `missing_api_key`
+before any network call.
+
+The client exposes three namespaces: `links`, `project`, and `qr`.
+
+## Links
+
+```ruby
+# Create
+link = rerout.links.create(
+  Rerout::CreateLinkInput.new(target_url: 'https://example.com')
+)
+
+# List (paginated)
+page = rerout.links.list(limit: 25)
+page.links        # => [Rerout::Models::Link, ...]
+page.next_cursor  # => Integer or nil
+page = rerout.links.list(cursor: page.next_cursor) if page.next_cursor
+
+# Get one
+link = rerout.links.get('q4')
+
+# Update — only the fields you set are sent.
+rerout.links.update('q4', Rerout::UpdateLinkInput.new(is_active: false))
+
+# Delete (soft delete)
+rerout.links.delete('q4') # => { "deleted" => true }
+
+# Per-link stats (defaults to 30 days)
+stats = rerout.links.stats('q4', days: 7)
+stats.total_clicks
+```
+
+### Clearing fields on update
+
+`Rerout::UpdateLinkInput` distinguishes *"leave this field alone"* from *"set
+this field to null on the server"*. Pass `Rerout::CLEAR` to null a field:
+
+```ruby
+# Sends { "expires_at": null } — removes the link's expiry.
+rerout.links.update('q4', Rerout::UpdateLinkInput.new(expires_at: Rerout::CLEAR))
+
+# Sends { "target_url": "https://new.example.com" } — leaves everything else.
+rerout.links.update('q4', Rerout::UpdateLinkInput.new(target_url: 'https://new.example.com'))
+```
+
+An `UpdateLinkInput` with no fields set raises `Rerout::Error` (code
+`empty_update`) client-side without hitting the API.
+
+## Project
+
+```ruby
+# Aggregate stats across every link (defaults to 30 days).
+stats = rerout.project.stats(days: 30)
+stats.total_clicks
+stats.daily      # => [Rerout::Models::DailyClicksPoint, ...]
+stats.top_codes  # => [Rerout::Models::StatsBreakdown, ...]
+
+# Identity of the project that owns the API key.
+me = rerout.project.me
+me.slug
+```
+
+## QR
+
+`qr.url` is a pure builder — it never touches the network:
+
+```ruby
+rerout.qr.url('q4')
+# => "https://api.rerout.co/v1/links/q4/qr"
+
+rerout.qr.url('q4', Rerout::QrOptions.new(size: 12, ecc: 'H', domain: 'go.brand.com'))
+# => "https://api.rerout.co/v1/links/q4/qr?size=12&ecc=H&domain=go.brand.com"
+```
+
+`qr.svg` fetches the rendered SVG from the API with the bearer token attached:
+
+```ruby
+svg = rerout.qr.svg('q4', Rerout::QrOptions.new(size: 16))
+File.write('q4.svg', svg)
+```
+
+QR options: `size` (1–32), `margin` (0–16), `ecc` (`L`/`M`/`Q`/`H`), `domain`,
+and `refresh` (`true` is serialized as `1`; a string is sent verbatim).
+
+## Webhook signature verification
+
+Rerout signs every webhook delivery with an `X-Rerout-Signature` header. Verify
+it before trusting the payload:
+
+```ruby
+ok = Rerout::Webhooks.verify_signature(
+  raw_body: request.raw_post,
+  signature_header: request.headers['X-Rerout-Signature'],
+  secret: ENV.fetch('REROUT_WEBHOOK_SECRET')
+)
+
+head(:unauthorized) and return unless ok
+```
+
+`Rerout.verify_signature` is a module-level shortcut for the same method. The
+HMAC-SHA256 comparison runs in constant time, and a five-minute timestamp
+tolerance guards against replay attacks. Pass `tolerance_seconds: 0` to disable
+the timestamp check. The method never raises — it returns `false` for every
+failure mode (malformed header, wrong secret, stale timestamp, tampered body).
+
+## Error handling
+
+Every failure raises `Rerout::Error`:
+
+```ruby
+begin
+  rerout.links.get('does-not-exist')
+rescue Rerout::Error => e
+  e.code             # => "not_found" (stable string, API or synthetic)
+  e.status           # => 404 (HTTP status, or 0 for network/timeout failures)
+  e.message          # => human-readable description
+  e.path             # => API path, when supplied by the server
+  e.timestamp        # => server timestamp, when supplied
+  e.rate_limited?    # => true when status == 429
+  e.server_error?    # => true for HTTP 5xx
+end
+```
+
+When the server responds without a JSON body the SDK fills in a synthetic
+`code`: `unauthorized` (401), `forbidden` (403), `not_found` (404),
+`rate_limited` (429), `server_error` (5xx), `client_error` (other 4xx),
+`network_error` (connection failure), `timeout`, and `unexpected_response`
+(a 2xx body that is not valid JSON).
+
+## License
+
+MIT — see [LICENSE](LICENSE), a copy of the workspace
+[LICENSE](https://github.com/ModestNerds-Co/rerout-sdks/blob/main/LICENSE).
+
+## Links
+
+- API docs: <https://rerout.co/docs>
+- Source: <https://github.com/ModestNerds-Co/rerout-sdks>

data/lib/rerout/client.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+require_relative 'version'
+require_relative 'error'
+require_relative 'create_link_input'
+require_relative 'update_link_input'
+require_relative 'qr_options'
+require_relative 'webhooks'
+require_relative 'models'
+require_relative 'links'
+require_relative 'project'
+require_relative 'qr'
+
+module Rerout
+  # Default production API base URL.
+  DEFAULT_BASE_URL = 'https://api.rerout.co'
+
+  # Main entry point — construct one of these per project API key and re-use
+  # it across requests. Thread-safe so long as the injected Faraday connection
+  # is thread-safe (Faraday's default `Net::HTTP` adapter is).
+  #
+  # @example
+  #   rerout = Rerout::Client.new(api_key: ENV.fetch('REROUT_API_KEY'))
+  #   link = rerout.links.create(Rerout::CreateLinkInput.new(target_url: 'https://example.com'))
+  #   puts link.short_url
+  class Client
+    # @return [String] resolved base URL with trailing slashes stripped.
+    attr_reader :base_url
+
+    # @return [Resources::Links] link namespace.
+    attr_reader :links
+    # @return [Resources::Project] project namespace.
+    attr_reader :project
+    # @return [Resources::Qr] QR namespace.
+    attr_reader :qr
+
+    # @param api_key [String] project API key (`rrk_…`). Required.
+    # @param base_url [String, nil] override base URL. Defaults to `https://api.rerout.co`.
+    # @param connection [Faraday::Connection, nil] inject a Faraday connection
+    #   (useful for the test adapter or for sharing connection pools).
+    # @param timeout [Integer] per-request timeout in seconds. Default 30.
+    # @param user_agent [String, nil] override the default `User-Agent` header.
+    def initialize(api_key:, base_url: nil, connection: nil, timeout: 30, user_agent: nil)
+      if api_key.nil? || !api_key.is_a?(String) || api_key.strip.empty?
+        raise Error.new(
+          code: 'missing_api_key',
+          message: 'A project API key is required to construct Rerout::Client.',
+          status: 0
+        )
+      end
+
+      @api_key = api_key
+      @base_url = (base_url || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, '')
+      @timeout = timeout
+      @user_agent = user_agent || "rerout-ruby/#{Rerout::VERSION}"
+      @connection = connection || default_connection
+
+      @links = Resources::Links.new(self)
+      @project = Resources::Project.new(self)
+      @qr = Resources::Qr.new(self)
+    end
+
+    # Perform a JSON request against the Rerout API.
+    #
+    # @api private
+    # @param method [Symbol] :get, :post, :patch, :delete
+    # @param path [String] starts with `/`, includes any path params.
+    # @param query [Hash, nil] query string params.
+    # @param body [Object, nil] body to be JSON-encoded.
+    # @return [Hash, Array, String, nil] parsed JSON body, raw text for non-JSON
+    #   success bodies that the caller opted into via `raw: true`, or nil for
+    #   204 No Content.
+    def request(method:, path:, query: nil, body: nil, raw: false)
+      headers = base_headers
+      payload = nil
+      if body
+        payload = JSON.generate(body)
+        headers['Content-Type'] = 'application/json'
+      end
+
+      response = perform_request(method: method, path: path, query: query,
+                                 headers: headers, payload: payload)
+
+      handle_response(response, raw: raw)
+    end
+
+    private
+
+    def perform_request(method:, path:, query:, headers:, payload:)
+      full_url = "#{@base_url}#{path}"
+      @connection.public_send(method) do |req|
+        req.url(full_url)
+        req.params.update(query) if query && !query.empty?
+        headers.each { |k, v| req.headers[k] = v }
+        req.body = payload if payload
+        req.options.timeout = @timeout if @timeout
+        req.options.open_timeout = @timeout if @timeout
+      end
+    rescue Faraday::TimeoutError => e
+      raise Error.new(code: 'timeout', message: e.message || 'Request timed out.', status: 0, details: e)
+    rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise Error.new(code: 'network_error', message: e.message || 'Network failure.', status: 0, details: e)
+    rescue Faraday::Error => e
+      raise Error.new(code: 'network_error', message: e.message || 'Faraday error.', status: 0, details: e)
+    end
+
+    def base_headers
+      {
+        'Authorization' => "Bearer #{@api_key}",
+        'Accept' => 'application/json',
+        'User-Agent' => @user_agent
+      }
+    end
+
+    def handle_response(response, raw:)
+      status = response.status
+      body = response.body.to_s
+
+      raise parse_error(status, body) unless status.between?(200, 299)
+      return nil if status == 204 || body.empty?
+      return body if raw
+
+      begin
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise Error.new(
+          code: 'unexpected_response',
+          message: 'Rerout returned a non-JSON success body.',
+          status: status,
+          details: { body: body, error: e.message }
+        )
+      end
+    end
+
+    def parse_error(status, body)
+      if body.empty?
+        return Error.new(
+          code: synthetic_code(status),
+          message: "Rerout returned HTTP #{status} with no body.",
+          status: status
+        )
+      end
+
+      begin
+        parsed = JSON.parse(body)
+      rescue JSON::ParserError
+        return Error.new(
+          code: synthetic_code(status),
+          message: "Rerout returned HTTP #{status} (non-JSON body).",
+          status: status,
+          details: { body: body }
+        )
+      end
+
+      Error.new(
+        code: parsed['code'] || synthetic_code(status),
+        message: parsed['message'] || "Rerout returned HTTP #{status}.",
+        status: status,
+        path: parsed['path'],
+        timestamp: parsed['timestamp'],
+        details: parsed
+      )
+    end
+
+    def synthetic_code(status)
+      case status
+      when 401 then 'unauthorized'
+      when 403 then 'forbidden'
+      when 404 then 'not_found'
+      when 429 then 'rate_limited'
+      when 500..599 then 'server_error'
+      else 'client_error'
+      end
+    end
+
+    def default_connection
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :url_encoded
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/rerout/create_link_input.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Request body for `POST /v1/links`. Only `target_url` is required —
+  # everything else is optional and omitted from the payload when not set.
+  class CreateLinkInput
+    attr_reader :target_url, :domain_hostname, :code, :expires_at,
+                :seo_title, :seo_description, :seo_image_url,
+                :seo_canonical_url, :seo_noindex
+
+    # @param target_url [String] required, the destination URL.
+    # @param domain_hostname [String, nil] verified custom domain (e.g. `go.brand.com`).
+    # @param code [String, nil] custom path. Only allowed with a verified `domain_hostname`.
+    # @param expires_at [Integer, nil] unix seconds.
+    # @param seo_title [String, nil]
+    # @param seo_description [String, nil]
+    # @param seo_image_url [String, nil] absolute https:// URL.
+    # @param seo_canonical_url [String, nil]
+    # @param seo_noindex [Boolean, nil] default server-side: `true`.
+    def initialize(target_url:, domain_hostname: nil, code: nil, expires_at: nil,
+                   seo_title: nil, seo_description: nil, seo_image_url: nil,
+                   seo_canonical_url: nil, seo_noindex: nil)
+      raise ArgumentError, 'target_url is required' if target_url.nil? || target_url.to_s.empty?
+
+      @target_url = target_url
+      @domain_hostname = domain_hostname
+      @code = code
+      @expires_at = expires_at
+      @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. Fields are only included when set.
+    def to_h
+      hash = { 'target_url' => target_url }
+      hash['domain_hostname'] = domain_hostname unless domain_hostname.nil?
+      hash['code'] = code unless code.nil?
+      hash['expires_at'] = expires_at unless expires_at.nil?
+      hash['seo_title'] = seo_title unless seo_title.nil?
+      hash['seo_description'] = seo_description unless seo_description.nil?
+      hash['seo_image_url'] = seo_image_url unless seo_image_url.nil?
+      hash['seo_canonical_url'] = seo_canonical_url unless seo_canonical_url.nil?
+      hash['seo_noindex'] = seo_noindex unless seo_noindex.nil?
+      hash
+    end
+  end
+end

data/lib/rerout/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Raised for any Rerout API failure — bad request, auth issue, rate limit,
+  # network failure, timeout, or unparseable response.
+  #
+  # The {#code} field carries the stable string identifier returned by the
+  # Rerout API (e.g. `bad_target_url`, `rate_limited`, `not_found`) so callers
+  # can branch on it without parsing the human-readable {#message}.
+  #
+  # For network/timeout/parse failures the {#code} is one of the synthetic
+  # values: `network_error`, `timeout`, `unexpected_response`, `unauthorized`,
+  # `forbidden`, `not_found`, `rate_limited`, `server_error`, `client_error`,
+  # `missing_api_key`.
+  class Error < StandardError
+    # @return [String] stable error code, either from the API or synthetic.
+    attr_reader :code
+
+    # @return [Integer] HTTP status, or 0 when the request never reached the server.
+    attr_reader :status
+
+    # @return [String, nil] API path that returned the error, when available.
+    attr_reader :path
+
+    # @return [String, nil] ISO-8601 server timestamp, when supplied.
+    attr_reader :timestamp
+
+    # @return [Object, nil] raw parsed payload or original cause.
+    attr_reader :details
+
+    def initialize(message:, code:, status: 0, path: nil, timestamp: nil, details: nil)
+      super(message)
+      @code = code
+      @status = status
+      @path = path
+      @timestamp = timestamp
+      @details = details
+    end
+
+    # @return [Boolean] true when the failure is HTTP 429.
+    def rate_limited?
+      status == 429
+    end
+
+    # @return [Boolean] true when the failure is HTTP 5xx.
+    def server_error?
+      status >= 500 && status < 600
+    end
+
+    # A developer-friendly description. Kept separate from {#message} (the raw
+    # human message) so logging the error shows the structured fields without
+    # the bare message losing them.
+    def inspect
+      "#<Rerout::Error code=#{code.inspect} status=#{status} " \
+        "message=#{message.inspect} path=#{path.inspect} " \
+        "timestamp=#{timestamp.inspect}>"
+    end
+  end
+end

data/lib/rerout/links.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module Rerout
+  module Resources
+    # Link operations namespace.
+    class Links
+      # @param client [Rerout::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new short link.
+      #
+      # @param input [Rerout::CreateLinkInput, Hash] the request body.
+      # @return [Rerout::Models::Link]
+      def create(input)
+        body = coerce_input(input)
+        response = @client.request(method: :post, path: '/v1/links', body: body)
+        Models::Link.from_hash(response)
+      end
+
+      # Paginated list of links.
+      #
+      # @param cursor [Integer, nil]
+      # @param limit [Integer, nil]
+      # @return [Rerout::Models::ListLinksResult]
+      def list(cursor: nil, limit: nil)
+        query = {}
+        query['cursor'] = cursor unless cursor.nil?
+        query['limit'] = limit unless limit.nil?
+        response = @client.request(method: :get, path: '/v1/links', query: query)
+        Models::ListLinksResult.from_hash(response)
+      end
+
+      # Fetch a single link.
+      #
+      # @param code [String]
+      # @return [Rerout::Models::Link]
+      def get(code)
+        response = @client.request(method: :get, path: link_path(code))
+        Models::Link.from_hash(response)
+      end
+
+      # Update a link. Only fields set on `input` are sent.
+      #
+      # @param code [String]
+      # @param input [Rerout::UpdateLinkInput]
+      # @return [Rerout::Models::Link]
+      def update(code, input)
+        raise ArgumentError, 'input must be a Rerout::UpdateLinkInput' unless input.is_a?(UpdateLinkInput)
+        if input.empty?
+          raise Error.new(
+            code: 'empty_update',
+            message: 'UpdateLinkInput has no fields set; refusing to send empty PATCH.',
+            status: 0
+          )
+        end
+
+        response = @client.request(method: :patch, path: link_path(code), body: input.to_h)
+        Models::Link.from_hash(response)
+      end
+
+      # Soft-delete a link.
+      #
+      # @param code [String]
+      # @return [Hash] `{ "deleted" => true }`
+      def delete(code)
+        @client.request(method: :delete, path: link_path(code))
+      end
+
+      # Per-link click stats. Defaults to 30 days.
+      #
+      # @param code [String]
+      # @param days [Integer]
+      # @return [Rerout::Models::LinkStats]
+      def stats(code, days: 30)
+        response = @client.request(
+          method: :get,
+          path: "#{link_path(code)}/stats",
+          query: { 'days' => days }
+        )
+        Models::LinkStats.from_hash(response)
+      end
+
+      private
+
+      def link_path(code)
+        raise ArgumentError, 'code is required' if code.nil? || code.to_s.empty?
+
+        "/v1/links/#{ERB::Util.url_encode(code.to_s)}"
+      end
+
+      def coerce_input(input)
+        case input
+        when CreateLinkInput then input.to_h
+        when Hash then input
+        else
+          raise ArgumentError, 'input must be a Rerout::CreateLinkInput or Hash'
+        end
+      end
+    end
+  end
+end