tly-url-shortener-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6069fa9be1fa0d2823f085082d68ce8ecec96b178ed0ecbca27370d2f70c6415
+  data.tar.gz: 74e359fee6e6c76f39e91efb6b855aaadc3f55dabb7fffa3195c84b053c70825
+SHA512:
+  metadata.gz: a970c9ecb36366d6a4fd392a52b3d070d39f04edede66c7791a2b3ef319af4e4cd0089fd2f0980f5972ce55cda5df357ed3f8066f67c56bd0c10bf288a5ef3fe
+  data.tar.gz: 113411facbe63af3f98062d13ed1801df7cda70acd5f494a4d538801c794f0b0fa3531eafcc9bc62fdbcc922481be281132e3dce3bc7d3771767a3a5f634e9ca

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-02-17
+
+- Initial release.
+- Added full Ruby client coverage for T.LY endpoints in the provided Postman collection.
+- Added typed error handling and response wrapper.
+- Added test suite and gem packaging files.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 T.LY
+
+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,172 @@
+# T.LY Ruby URL Shortener API
+
+Ruby client library for the [T.LY API](https://t.ly).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tly-url-shortener-api"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install tly-url-shortener-api
+```
+
+## Quick Start
+
+```ruby
+require "tly_url_shortener_api"
+
+client = Tly::UrlShortenerApi::Client.new(api_token: ENV.fetch("TLY_API_TOKEN"))
+
+response = client.shorten_link(
+  long_url: "https://example.com/very/long/path",
+  domain: "https://t.ly",
+  description: "My short link"
+)
+
+puts response.status
+puts response.body
+```
+
+## Authentication
+
+This gem sends your API token as a bearer token header:
+
+```http
+Authorization: Bearer <YOUR_TOKEN>
+```
+
+## Available API Methods
+
+### OneLink Stats
+
+- `onelink_stats(short_url:, start_date: nil, end_date: nil)`
+- `delete_onelink_stats(short_url:)`
+
+### ShortLink Management
+
+- `shorten_link(long_url:, domain: nil, expire_at_datetime: nil, description: nil, public_stats: nil, meta: nil)`
+- `get_link(short_url:)`
+- `update_link(short_url:, long_url: nil, expire_at_datetime: nil, description: nil, public_stats: nil, meta: nil)`
+- `delete_link(short_url:)`
+- `expand_link(short_url:, password: nil)`
+- `list_links(search: nil, tag_ids: nil, pixel_ids: nil, start_date: nil, end_date: nil, domains: nil)`
+- `bulk_shorten_links(links:, domain: nil, tags: nil, pixels: nil)`
+- `bulk_update_links(links:, tags: nil, pixels: nil)`
+
+### ShortLink Stats
+
+- `link_stats(short_url:, start_date: nil, end_date: nil)`
+
+### UTM Presets
+
+- `create_utm_preset(name:, source:, medium:, campaign:, content: nil, term: nil)`
+- `list_utm_presets`
+- `get_utm_preset(id:)`
+- `update_utm_preset(id:, name: nil, source: nil, medium: nil, campaign: nil, content: nil, term: nil)`
+- `delete_utm_preset(id:)`
+
+### OneLinks
+
+- `list_onelinks(page: nil)`
+
+### Pixels
+
+- `create_pixel(name:, pixel_id:, pixel_type:)`
+- `list_pixels`
+- `get_pixel(id:)`
+- `update_pixel(id:, name: nil, pixel_id: nil, pixel_type: nil)`
+- `delete_pixel(id:)`
+
+### QR Codes
+
+- `get_qr_code(short_url:, output: nil, format: nil)`
+- `update_qr_code(short_url:, image: nil, background_color: nil, corner_dots_color: nil, dots_color: nil, dots_style: nil, corner_style: nil)`
+
+### Tags
+
+- `list_tags`
+- `create_tag(tag:)`
+- `get_tag(id:)`
+- `update_tag(id:, tag:)`
+- `delete_tag(id:)`
+
+## Response Object
+
+Every method returns `Tly::UrlShortenerApi::Response` with:
+
+- `status` - HTTP status code
+- `headers` - response headers hash (lowercase keys)
+- `body` - parsed JSON (Hash/Array) or raw body string
+- `raw_body` - unparsed body string
+- `success?` - true for HTTP 2xx
+
+## Error Handling
+
+Failed responses raise typed errors:
+
+- `Tly::UrlShortenerApi::AuthenticationError`
+- `Tly::UrlShortenerApi::PermissionError`
+- `Tly::UrlShortenerApi::NotFoundError`
+- `Tly::UrlShortenerApi::ValidationError`
+- `Tly::UrlShortenerApi::RateLimitError`
+- `Tly::UrlShortenerApi::ServerError`
+- `Tly::UrlShortenerApi::TransportError` (network/timeout/connection failures)
+
+```ruby
+begin
+  client.get_link(short_url: "https://t.ly/missing")
+rescue Tly::UrlShortenerApi::NotFoundError => e
+  puts e.status
+  puts e.response_body
+end
+```
+
+## Configure Base URL and Timeouts
+
+```ruby
+client = Tly::UrlShortenerApi::Client.new(
+  api_token: ENV.fetch("TLY_API_TOKEN"),
+  base_url: "https://api.t.ly",
+  open_timeout: 5,
+  read_timeout: 20
+)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## Release to RubyGems
+
+1. Update version in `lib/tly/url_shortener_api/version.rb`.
+2. Update `CHANGELOG.md`.
+3. Build the gem:
+
+```bash
+gem build tly-url-shortener-api.gemspec
+```
+
+4. Push to RubyGems:
+
+```bash
+gem push tly-url-shortener-api-<version>.gem
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/tly/url_shortener_api/client.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "net/http"
+require "uri"
+
+module Tly
+  module UrlShortenerApi
+    class Client
+      DEFAULT_BASE_URL = "https://api.t.ly"
+
+      attr_reader :api_token, :base_url, :open_timeout, :read_timeout, :user_agent
+
+      def initialize(api_token:, base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 30, user_agent: default_user_agent)
+        token = api_token.to_s.strip
+        raise ArgumentError, "api_token is required" if token.empty?
+
+        @api_token = token
+        @base_url = normalize_base_url(base_url)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @user_agent = user_agent
+      end
+
+      # OneLink Stats Management
+      def onelink_stats(short_url:, start_date: nil, end_date: nil)
+        request(
+          :get,
+          "/api/v1/onelink/stats",
+          query: { short_url: short_url, start_date: start_date, end_date: end_date }
+        )
+      end
+
+      def delete_onelink_stats(short_url:)
+        request(:delete, "/api/v1/onelink/stat", body: { short_url: short_url })
+      end
+
+      # ShortLink Management
+      def shorten_link(long_url:, domain: nil, expire_at_datetime: nil, description: nil, public_stats: nil, meta: nil)
+        request(
+          :post,
+          "/api/v1/link/shorten",
+          body: {
+            long_url: long_url,
+            domain: domain,
+            expire_at_datetime: expire_at_datetime,
+            description: description,
+            public_stats: public_stats,
+            meta: meta
+          }
+        )
+      end
+
+      def get_link(short_url:)
+        request(:get, "/api/v1/link", query: { short_url: short_url })
+      end
+
+      def update_link(short_url:, long_url: nil, expire_at_datetime: nil, description: nil, public_stats: nil, meta: nil)
+        request(
+          :put,
+          "/api/v1/link",
+          body: {
+            short_url: short_url,
+            long_url: long_url,
+            expire_at_datetime: expire_at_datetime,
+            description: description,
+            public_stats: public_stats,
+            meta: meta
+          }
+        )
+      end
+
+      def delete_link(short_url:)
+        request(:delete, "/api/v1/link", body: { short_url: short_url })
+      end
+
+      def expand_link(short_url:, password: nil)
+        request(:post, "/api/v1/link/expand", body: { short_url: short_url, password: password })
+      end
+
+      def list_links(search: nil, tag_ids: nil, pixel_ids: nil, start_date: nil, end_date: nil, domains: nil)
+        request(
+          :get,
+          "/api/v1/link/list",
+          query: {
+            search: search,
+            tag_ids: tag_ids,
+            pixel_ids: pixel_ids,
+            start_date: start_date,
+            end_date: end_date,
+            domains: domains
+          }
+        )
+      end
+
+      def bulk_shorten_links(links:, domain: nil, tags: nil, pixels: nil)
+        request(
+          :post,
+          "/api/v1/link/bulk",
+          body: {
+            domain: domain,
+            links: links,
+            tags: tags,
+            pixels: pixels
+          }
+        )
+      end
+
+      def bulk_update_links(links:, tags: nil, pixels: nil)
+        request(
+          :post,
+          "/api/v1/link/bulk/update",
+          body: {
+            links: links,
+            tags: tags,
+            pixels: pixels
+          }
+        )
+      end
+
+      # ShortLink Stats
+      def link_stats(short_url:, start_date: nil, end_date: nil)
+        request(:get, "/api/v1/link/stats", query: { short_url: short_url, start_date: start_date, end_date: end_date })
+      end
+
+      # UTM Preset Management
+      def create_utm_preset(name:, source:, medium:, campaign:, content: nil, term: nil)
+        request(
+          :post,
+          "/api/v1/link/utm-preset",
+          body: {
+            name: name,
+            source: source,
+            medium: medium,
+            campaign: campaign,
+            content: content,
+            term: term
+          }
+        )
+      end
+
+      def list_utm_presets
+        request(:get, "/api/v1/link/utm-preset")
+      end
+
+      def get_utm_preset(id:)
+        request(:get, path_with_id("/api/v1/link/utm-preset/:id", id))
+      end
+
+      def update_utm_preset(id:, name: nil, source: nil, medium: nil, campaign: nil, content: nil, term: nil)
+        request(
+          :put,
+          path_with_id("/api/v1/link/utm-preset/:id", id),
+          body: {
+            name: name,
+            source: source,
+            medium: medium,
+            campaign: campaign,
+            content: content,
+            term: term
+          }
+        )
+      end
+
+      def delete_utm_preset(id:)
+        request(:delete, path_with_id("/api/v1/link/utm-preset/:id", id))
+      end
+
+      # OneLink Management
+      def list_onelinks(page: nil)
+        request(:get, "/api/v1/onelink/list", query: { page: page })
+      end
+
+      # Pixel Management
+      def create_pixel(name:, pixel_id:, pixel_type:)
+        request(:post, "/api/v1/link/pixel", body: { name: name, pixel_id: pixel_id, pixel_type: pixel_type })
+      end
+
+      def list_pixels
+        request(:get, "/api/v1/link/pixel")
+      end
+
+      def get_pixel(id:)
+        request(:get, path_with_id("/api/v1/link/pixel/:id", id))
+      end
+
+      def update_pixel(id:, name: nil, pixel_id: nil, pixel_type: nil)
+        request(
+          :put,
+          path_with_id("/api/v1/link/pixel/:id", id),
+          body: {
+            id: id,
+            name: name,
+            pixel_id: pixel_id,
+            pixel_type: pixel_type
+          }
+        )
+      end
+
+      def delete_pixel(id:)
+        request(:delete, path_with_id("/api/v1/link/pixel/:id", id))
+      end
+
+      # QR Code Management
+      def get_qr_code(short_url:, output: nil, format: nil)
+        request(
+          :get,
+          "/api/v1/link/qr-code",
+          query: {
+            short_url: short_url,
+            output: output,
+            format: format
+          }
+        )
+      end
+
+      def update_qr_code(short_url:, image: nil, background_color: nil, corner_dots_color: nil, dots_color: nil,
+                         dots_style: nil, corner_style: nil)
+        request(
+          :put,
+          "/api/v1/link/qr-code",
+          body: {
+            short_url: short_url,
+            image: image,
+            background_color: background_color,
+            corner_dots_color: corner_dots_color,
+            dots_color: dots_color,
+            dots_style: dots_style,
+            corner_style: corner_style
+          }
+        )
+      end
+
+      # Tag Management
+      def list_tags
+        request(:get, "/api/v1/link/tag")
+      end
+
+      def create_tag(tag:)
+        request(:post, "/api/v1/link/tag", body: { tag: tag })
+      end
+
+      def get_tag(id:)
+        request(:get, path_with_id("/api/v1/link/tag/:id", id))
+      end
+
+      def update_tag(id:, tag:)
+        request(:put, path_with_id("/api/v1/link/tag/:id", id), body: { tag: tag })
+      end
+
+      def delete_tag(id:)
+        request(:delete, path_with_id("/api/v1/link/tag/:id", id))
+      end
+
+      # Low-level request for endpoints added in the future.
+      def request(method, path, query: nil, body: nil, headers: {})
+        uri = build_uri(path, query)
+
+        req = build_request(method, uri)
+        default_headers.each { |key, value| req[key] = value }
+        headers.each { |key, value| req[key] = value }
+
+        if body
+          req["Content-Type"] ||= "application/json"
+          req.body = JSON.generate(compact_payload(body))
+        end
+
+        response = execute_request(uri, req)
+        raise_for_status!(response)
+        response
+      end
+
+      private
+
+      def default_user_agent
+        "tly-url-shortener-api/#{Tly::UrlShortenerApi::VERSION}"
+      end
+
+      def normalize_base_url(url)
+        normalized = url.to_s.strip.sub(%r{/+\z}, "")
+        raise ArgumentError, "base_url is required" if normalized.empty?
+
+        uri = URI.parse(normalized)
+        return normalized if uri.is_a?(URI::HTTP) && uri.host
+
+        raise ArgumentError, "base_url must be an absolute HTTP(S) URL"
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, "base_url must be a valid URL: #{e.message}"
+      end
+
+      def default_headers
+        {
+          "Authorization" => "Bearer #{api_token}",
+          "Accept" => "application/json",
+          "User-Agent" => user_agent
+        }
+      end
+
+      def build_request(method, uri)
+        klass = {
+          get: Net::HTTP::Get,
+          post: Net::HTTP::Post,
+          put: Net::HTTP::Put,
+          patch: Net::HTTP::Patch,
+          delete: Net::HTTP::Delete
+        }[method.to_sym]
+
+        raise ArgumentError, "Unsupported HTTP method: #{method}" unless klass
+
+        klass.new(uri)
+      end
+
+      def execute_request(uri, request)
+        raw_response = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: open_timeout,
+          read_timeout: read_timeout
+        ) do |http|
+          http.request(request)
+        end
+
+        parsed = parse_response_body(raw_response)
+
+        Response.new(
+          status: raw_response.code.to_i,
+          headers: normalize_headers(raw_response),
+          body: parsed,
+          raw_body: raw_response.body.to_s
+        )
+      rescue IOError, EOFError, SocketError, SystemCallError, Timeout::Error => e
+        raise TransportError.new("T.LY API transport error: #{e.message}")
+      end
+
+      def parse_response_body(raw_response)
+        raw_body = raw_response.body.to_s
+        content_type = raw_response["Content-Type"].to_s.downcase
+
+        return raw_body unless content_type.include?("json")
+
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        raw_body
+      end
+
+      def normalize_headers(raw_response)
+        raw_response.each_header.each_with_object({}) do |(key, value), headers|
+          headers[key.downcase] = value
+        end
+      end
+
+      def raise_for_status!(response)
+        return if response.success?
+
+        message = extract_error_message(response)
+        klass = error_class_for(response.status)
+        raise klass.new(message, status: response.status, response_body: response.body, headers: response.headers)
+      end
+
+      def extract_error_message(response)
+        body = response.body
+        return body["message"].to_s if body.is_a?(Hash) && body["message"]
+        return body["error"].to_s if body.is_a?(Hash) && body["error"]
+
+        "T.LY API request failed with status #{response.status}"
+      end
+
+      def error_class_for(status)
+        case status
+        when 400, 422 then ValidationError
+        when 401 then AuthenticationError
+        when 403 then PermissionError
+        when 404 then NotFoundError
+        when 429 then RateLimitError
+        when 400..499 then ClientError
+        else ServerError
+        end
+      end
+
+      def build_uri(path, query)
+        uri = URI.parse("#{base_url}#{path}")
+        query_string = build_query_string(query)
+        uri.query = query_string unless query_string.nil? || query_string.empty?
+        uri
+      end
+
+      def build_query_string(query)
+        return nil if query.nil?
+
+        pairs = []
+        flatten_query_value(query).each do |key, value|
+          next if value.nil?
+
+          pairs << "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+        end
+        pairs.join("&")
+      end
+
+      def flatten_query_value(value, prefix = nil, output = [])
+        case value
+        when Hash
+          value.each do |key, nested_value|
+            nested_key = prefix ? "#{prefix}[#{key}]" : key.to_s
+            flatten_query_value(nested_value, nested_key, output)
+          end
+        when Array
+          value.each_with_index do |nested_value, index|
+            flatten_query_value(nested_value, "#{prefix}[#{index}]", output)
+          end
+        else
+          output << [prefix, value]
+        end
+        output
+      end
+
+      def compact_payload(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), obj|
+            compacted = compact_payload(nested_value)
+            obj[key] = compacted unless compacted.nil?
+          end
+        when Array
+          value.map { |v| compact_payload(v) }.compact
+        else
+          value
+        end
+      end
+
+      def path_with_id(path, id)
+        path.sub(":id", escape_path_component(id))
+      end
+
+      def escape_path_component(component)
+        CGI.escape(component.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end

data/lib/tly/url_shortener_api/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tly
+  module UrlShortenerApi
+    class Error < StandardError
+      attr_reader :status, :response_body, :headers
+
+      def initialize(message = "T.LY API request failed", status: nil, response_body: nil, headers: nil)
+        super(message)
+        @status = status
+        @response_body = response_body
+        @headers = headers || {}
+      end
+    end
+
+    class ClientError < Error; end
+    class AuthenticationError < ClientError; end
+    class PermissionError < ClientError; end
+    class NotFoundError < ClientError; end
+    class ValidationError < ClientError; end
+    class RateLimitError < ClientError; end
+    class ServerError < Error; end
+    class TransportError < Error; end
+  end
+end

data/lib/tly/url_shortener_api/response.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Tly
+  module UrlShortenerApi
+    class Response
+      attr_reader :status, :headers, :body, :raw_body
+
+      def initialize(status:, headers:, body:, raw_body:)
+        @status = status
+        @headers = headers
+        @body = body
+        @raw_body = raw_body
+      end
+
+      def success?
+        (200..299).cover?(status)
+      end
+    end
+  end
+end

data/lib/tly/url_shortener_api/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tly
+  module UrlShortenerApi
+    VERSION = "0.1.0"
+  end
+end

data/lib/tly/url_shortener_api.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "tly/url_shortener_api/version"
+require "tly/url_shortener_api/errors"
+require "tly/url_shortener_api/response"
+require "tly/url_shortener_api/client"
+
+module Tly
+  module UrlShortenerApi
+    class << self
+      def client(api_token:, **options)
+        Client.new(api_token: api_token, **options)
+      end
+    end
+  end
+end

data/lib/tly_url_shortener_api.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "tly/url_shortener_api"

data/test/client_test.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class ClientTest < Minitest::Test
+  def test_shorten_link_sends_bearer_and_json
+    with_server do |server|
+      client = build_client(server)
+
+      response = client.shorten_link(
+        long_url: "https://example.com/long/path",
+        description: "Example link"
+      )
+
+      request = server.requests.last
+      body = JSON.parse(request.body)
+
+      assert_equal 200, response.status
+      assert_equal true, response.body["ok"]
+      assert_equal "Bearer test_token", request.headers["authorization"]
+      assert_equal "application/json", request.headers["accept"]
+      assert_equal "https://example.com/long/path", body["long_url"]
+      assert_equal "Example link", body["description"]
+      refute body.key?("domain")
+    end
+  end
+
+  def test_list_links_serializes_indexed_array_query
+    with_server do |server|
+      client = build_client(server)
+
+      client.list_links(
+        tag_ids: [1, 2],
+        pixel_ids: [10],
+        domains: ["t.ly", "my.t.ly"]
+      )
+
+      query_string = server.requests.last.query_string
+
+      assert_includes query_string, "tag_ids%5B0%5D=1"
+      assert_includes query_string, "tag_ids%5B1%5D=2"
+      assert_includes query_string, "pixel_ids%5B0%5D=10"
+      assert_includes query_string, "domains%5B0%5D=t.ly"
+      assert_includes query_string, "domains%5B1%5D=my.t.ly"
+    end
+  end
+
+  def test_non_json_response_body_is_returned_raw
+    with_server(content_type: "image/png", body: "PNG_BINARY".b) do |server|
+      client = build_client(server)
+
+      response = client.get_qr_code(short_url: "https://t.ly/abc")
+
+      assert_equal "PNG_BINARY".b, response.body
+      assert_equal "PNG_BINARY".b, response.raw_body
+      assert_equal true, response.success?
+    end
+  end
+
+  def test_raises_typed_error_for_unauthorized
+    with_server(status: 401, body: JSON.generate({ message: "Unauthorized" })) do |server|
+      client = build_client(server)
+
+      error = assert_raises(Tly::UrlShortenerApi::AuthenticationError) do
+        client.get_link(short_url: "https://t.ly/missing")
+      end
+
+      assert_equal 401, error.status
+      assert_equal "Unauthorized", error.message
+    end
+  end
+
+  def test_parses_vendor_json_content_types
+    with_server(content_type: "application/problem+json", body: JSON.generate({ error: "problem" })) do |server|
+      client = build_client(server)
+      response = client.get_link(short_url: "https://t.ly/abc")
+
+      assert_equal({ "error" => "problem" }, response.body)
+    end
+  end
+
+  def test_raises_transport_error_for_network_failures
+    client = Tly::UrlShortenerApi::Client.new(
+      api_token: "test_token",
+      base_url: "https://api.t.ly"
+    )
+
+    Net::HTTP.stub(:start, proc { raise Errno::ECONNREFUSED, "Connection refused" }) do
+      error = assert_raises(Tly::UrlShortenerApi::TransportError) do
+        client.get_link(short_url: "https://t.ly/abc")
+      end
+
+      assert_includes error.message, "transport error"
+    end
+  end
+
+  def test_rejects_invalid_base_url
+    error = assert_raises(ArgumentError) do
+      Tly::UrlShortenerApi::Client.new(api_token: "token", base_url: "not-a-url")
+    end
+
+    assert_includes error.message, "absolute HTTP(S) URL"
+  end
+
+  private
+
+  def build_client(server)
+    Tly::UrlShortenerApi::Client.new(
+      api_token: "test_token",
+      base_url: "http://127.0.0.1:#{server.port}"
+    )
+  end
+
+  def with_server(status: 200, content_type: "application/json", body: JSON.generate({ ok: true }), &block)
+    server = TestHttpServer.new do |_req, res|
+      res.status = status
+      res["Content-Type"] = content_type
+      res.body = body
+    end
+
+    server.start
+    yield(server)
+  ensure
+    server&.stop
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "webrick"
+require "json"
+
+require "tly_url_shortener_api"
+
+class TestHttpServer
+  RequestCapture = Struct.new(
+    :request_method,
+    :path,
+    :query_string,
+    :headers,
+    :body,
+    keyword_init: true
+  )
+
+  attr_reader :port, :requests
+
+  def initialize(&handler)
+    @handler = handler
+    @requests = []
+    @server = WEBrick::HTTPServer.new(
+      Port: 0,
+      Logger: WEBrick::Log.new(File::NULL),
+      AccessLog: []
+    )
+
+    @server.mount_proc("/") do |req, res|
+      @requests << RequestCapture.new(
+        request_method: req.request_method,
+        path: req.path,
+        query_string: req.query_string,
+        headers: req.header.transform_values { |v| v.is_a?(Array) ? v.first : v },
+        body: req.body
+      )
+      @handler.call(req, res)
+    end
+  end
+
+  def start
+    @thread = Thread.new { @server.start }
+    @port = @server.config[:Port]
+    sleep 0.05
+  end
+
+  def stop
+    @server.shutdown
+    @thread.join if @thread
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: tly-url-shortener-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- T.LY
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-02-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.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'
+description: Ruby client for creating, managing, and analyzing short links with the
+  T.LY API.
+email:
+- support@t.ly
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tly/url_shortener_api.rb
+- lib/tly/url_shortener_api/client.rb
+- lib/tly/url_shortener_api/errors.rb
+- lib/tly/url_shortener_api/response.rb
+- lib/tly/url_shortener_api/version.rb
+- lib/tly_url_shortener_api.rb
+- test/client_test.rb
+- test/test_helper.rb
+homepage: https://t.ly
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://t.ly
+  source_code_uri: https://github.com/tly/url-shortener-ruby
+  changelog_uri: https://github.com/tly/url-shortener-ruby/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby client for the T.LY URL Shortener API
+test_files: []