sink-cool 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b80f9d22b726100b1e3e5b1ee1dd8db7e4de9bd154a33cfb42c2797333d1b8b
-  data.tar.gz: b7f8f0dab846a2f53bc5aa5704a6408c7a7c496276c9a60a1335fbb127e2829e
+  metadata.gz: 117661123578a6b91926715b23db4f780820b7cfe1f420e79a1afc37c962a01b
+  data.tar.gz: eb5bc2317aa7d9b6d973d811d0ed5ca938ddee0f6c445aadfed53fcfb8b34380
 SHA512:
-  metadata.gz: 50c9749e0271c7d9dcc870f515e773b352355db3e347b7e7d5a609cd21a36525f2a2ef86c57686ca4883dc69da845a2c6cd110da2bf219ca61d87a20bd91a023
-  data.tar.gz: e364f3d9217a4bbeeced34575d509b0699ffbbba93150fb0a15f6f989094c4a10ba4a038ff4ec99b0c4483878c3e03d0b3cf9ad218a757c4618bf34956a2c3a8
+  metadata.gz: ff112350ba6829bc44186218dd35cedf7f67e71fd8ae9ec3dd41213a56b35b038129e879f0f7f3230740629f42cc6725e003a7acfd71c71c89ee3f3408505cf0
+  data.tar.gz: c7d2cebbe780ea928b9e022caa8d24644f3b6525f063e24443d50ecf99e89a8a3e1f29a41b06dc4fe91b67b90224708c1fead5855e4f52f298c8fba582696a91

data/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.2.1 - 2026-07-25
+
+### Added
+
+- Derive `Link#short_link` from `base_url` and the slug on the read endpoints, which the API only returns for writes. A `shortLink` in the response still wins.
+
+## 0.2.0 - 2026-07-25
+
+### Added
+
+- `Sink::Link` value objects with snake_case readers, `Time` timestamps, predicate methods, `to_h`, and `[]` access to fields without a reader.
+- `Sink::Page` collections including `Enumerable`, exposing `cursor`, `complete?`, and `more?`.
+- `Sink::Tag` records with `name` and `count`.
+- `Client#each_link` to iterate every page without handling cursors manually.
+- Error subclasses for each API failure mode: `Sink::ValidationError`, `Unauthorized`, `Forbidden`, `NotFound`, `Conflict`, `StorageNotReady`, `RateLimited`, `ServerError`, `ConnectionError`, and `TimeoutError`.
+- `Sink::Error#data` for the validation details returned by the API.
+
+### Changed
+
+- **Breaking:** link endpoints return `Sink::Link` and `Sink::Page` objects instead of raw hashes and arrays. Call `to_h` for the previous key names in snake_case.
+- **Breaking:** link attributes are passed as snake_case keyword arguments and camelized for the API, so `redirectWithQuery` becomes `redirect_with_query`. Unknown attributes now raise `ArgumentError`.
+- **Breaking:** `create_link`, `edit_link`, and `upsert_link` take keyword arguments, with `url` required by all three and `slug` also required by `edit_link`.
+- **Breaking:** `delete_link` returns `true` instead of `nil`.
+- **Breaking:** `verify` returns a hash with snake_case symbol keys.
+- `expires_at` accepts a `Time`, a `Date`, or a unix timestamp and is sent as `expiration`.
+- Timeouts, TLS, and socket failures raise `Sink::Error` subclasses instead of leaking `Net::HTTP` exceptions.
+
+### Fixed
+
+- Skip blank `message` values when building error messages, so the Sink API `statusMessage` is no longer replaced by an empty string.
+- Read `statusText` as an error message source, matching newer Sink releases.
+- Validate the token before the base URL so an empty token reports the right argument.
+
 ## 0.1.2 - 2026-07-23
 
 ### Fixed

data/README.md

@@ -1,5 +1,9 @@
 # sink-cool
 
+[![CI](https://github.com/7a6163/sink-cool/actions/workflows/ci.yml/badge.svg)](https://github.com/7a6163/sink-cool/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/sink-cool.svg)](https://rubygems.org/gems/sink-cool)
+[![codecov](https://codecov.io/gh/7a6163/sink-cool/branch/main/graph/badge.svg)](https://codecov.io/gh/7a6163/sink-cool)
+
 Ruby client for the [Sink](https://sink.cool/) URL shortener API.
 
 Requires Ruby 3.3 or newer.
@@ -59,19 +63,17 @@ client = Sink::Client.new(
 client = Sink.client
 
 client.verify
+# => { name: "Sink", auth_method: "site-token", user_email: "admin@example.com", ... }
 
 client.create_link(
   url: "https://example.com/articles/1",
   slug: "article-1",
-  tags: ["articles"]
-)
-
-client.edit_link(
-  url: "https://example.com/articles/2",
-  slug: "article-1",
-  tags: ["articles"]
+  tags: ["articles"],
+  redirect_with_query: true,
+  expires_at: 1.week.from_now
 )
 
+client.edit_link(url: "https://example.com/articles/2", slug: "article-1")
 client.upsert_link(url: "https://example.com", slug: "example")
 client.link("example")
 client.links(limit: 20, sort: "newest", status: "active")
@@ -81,20 +83,111 @@ client.check_links(limit: 6, timeout: 6)
 client.delete_link("example")
 ```
 
-API responses are returned as Ruby hashes or arrays. Requests returning HTTP
-204 return `nil`.
+Attributes are snake_case and converted to the camelCase names the API expects,
+so `redirect_with_query` is sent as `redirectWithQuery`. Unknown attributes
+raise `ArgumentError` instead of being silently dropped by the server.
+`expires_at` accepts a `Time`, a `Date`, or a unix timestamp.
+
+### Links
+
+`create_link`, `edit_link`, `upsert_link`, and `link` all return a `Sink::Link`:
+
+```ruby
+link = client.create_link(url: "https://example.com", slug: "example")
+
+link.slug                  # => "example"
+link.short_link            # => "https://sink.example.com/example"
+link.created_at            # => 2026-07-24 12:00:00 UTC
+link.expires_at            # => Time or nil
+link.expired?              # => false
+link.cloaking?             # => false
+link.redirect_with_query?  # => true
+link.tags                  # => ["articles"]
+link.geo                   # => { "US" => "https://example.com/us" }
+link.to_h                  # => { slug: "example", url: "https://example.com", ... }
+link[:any_future_field]    # raw access to fields without a reader
+```
+
+The API only returns `shortLink` for the write endpoints, where it builds the
+value from the protocol and host of the request. `short_link` is therefore
+derived from `base_url` and the slug for `link`, `links`, and `search_links`,
+which matches the API as long as `base_url` is the Worker domain that serves the
+short links.
+
+`upsert_link` never overwrites an existing slug, so check which happened:
+
+```ruby
+link = client.upsert_link(url: "https://example.com", slug: "example")
+
+link.created?  # => true when the link was stored
+link.existing? # => true when the slug already pointed somewhere else
+```
+
+`delete_link` returns `true`.
+
+### Collections
+
+`links`, `search_links`, and `check_links` return a `Sink::Page`, which is
+`Enumerable`:
+
+```ruby
+page = client.links(limit: 20)
+
+page.map(&:slug)
+page.cursor     # => "..." pagination cursor
+page.complete?  # => false when more pages are available
+page.more?      # => true when a following page can be fetched
+```
+
+Use `each_link` to walk every page without handling cursors:
+
+```ruby
+client.each_link(tag: "articles") { |link| puts link.short_link }
+client.each_link.lazy.select(&:expired?).first(10)
+```
+
+`tags` returns `Sink::Tag` records with `name` and `count`.
 
 ## Errors
 
-Non-successful responses raise `Sink::Error`:
+Non-successful responses raise a subclass of `Sink::Error`, so a Rails
+controller can rescue the cases it cares about:
+
+```ruby
+class LinksController < ApplicationController
+  rescue_from Sink::NotFound, with: :not_found
+
+  def create
+    link = Sink.client.create_link(url: params[:url], slug: params[:slug])
+    render json: link.to_h, status: :created
+  rescue Sink::Conflict
+    render json: { error: "slug already taken" }, status: :conflict
+  end
+end
+```
+
+| Class | Raised for |
+| --- | --- |
+| `Sink::ValidationError` | 400, 422 (`error.data` holds the API details) |
+| `Sink::Unauthorized` | 401, usually a wrong site token |
+| `Sink::Forbidden` | 403, including preview mode |
+| `Sink::NotFound` | 404 |
+| `Sink::Conflict` | 409, the slug already exists |
+| `Sink::StorageNotReady` | 423, open Dashboard → Links once after deploying |
+| `Sink::RateLimited` | 429 |
+| `Sink::ServerError` | 5xx |
+| `Sink::TimeoutError` | open or read timeout |
+| `Sink::ConnectionError` | DNS, TLS, and socket failures |
+
+Every error exposes `status`, `message`, `body`, and `data`:
 
 ```ruby
 begin
   Sink.client.link("missing")
 rescue Sink::Error => error
-  error.status
-  error.message
-  error.body
+  error.status  # => 404
+  error.message # => "Not Found"
+  error.body    # => parsed response body
 end
 ```
 

data/lib/sink/client.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "net/http"
+require "openssl"
 require "uri"
 
 module Sink
@@ -12,48 +13,121 @@ module Sink
       put: Net::HTTP::Put
     }.freeze
 
+    LINK_ATTRIBUTES = %i[
+      url slug comment expiration expires_at title description image apple google
+      cloaking redirect_with_query password unsafe geo tags
+    ].freeze
+
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error].freeze
+    CONNECTION_ERRORS = [
+      IOError, SocketError, SystemCallError, Net::ProtocolError, OpenSSL::SSL::SSLError
+    ].freeze
+
     def initialize(base_url:, token:, open_timeout: 5, read_timeout: 30)
-      @base_url = validate_base_url(base_url)
       @token = token.to_s
+      raise ArgumentError, "token is required" if @token.empty?
+
+      @base_url = validate_base_url(base_url)
       @open_timeout = open_timeout
       @read_timeout = read_timeout
-      raise ArgumentError, "token is required" if @token.empty?
     end
 
-    def verify = request(:get, "/api/verify")
+    def verify = Keys.underscore_keys(request(:get, "/api/verify") || {})
 
-    def create_link(attributes) = request(:post, "/api/link/create", body: attributes)
+    def create_link(url:, **attributes)
+      build_link(request(:post, "/api/link/create", body: link_payload(attributes.merge(url: url))))
+    end
 
-    def edit_link(attributes) = request(:put, "/api/link/edit", body: attributes)
+    def edit_link(url:, slug:, **attributes)
+      build_link(request(:put, "/api/link/edit", body: link_payload(attributes.merge(url: url, slug: slug))))
+    end
 
-    def upsert_link(attributes) = request(:post, "/api/link/upsert", body: attributes)
+    def upsert_link(url:, **attributes)
+      build_link(request(:post, "/api/link/upsert", body: link_payload(attributes.merge(url: url))))
+    end
 
-    def delete_link(slug) = request(:post, "/api/link/delete", body: { slug: slug })
+    def delete_link(slug)
+      request(:post, "/api/link/delete", body: { "slug" => slug })
+      true
+    end
 
-    def link(slug) = request(:get, "/api/link/query", query: { slug: slug })
+    def link(slug) = build_link(request(:get, "/api/link/query", query: { slug: slug }))
 
     def links(limit: nil, cursor: nil, sort: nil, tag: nil, status: nil)
-      request(:get, "/api/link/list", query: {
+      body = request(:get, "/api/link/list", query: {
         limit: limit, cursor: cursor, sort: sort, tag: tag, status: status
       })
+
+      link_page(body)
+    end
+
+    def each_link(**options)
+      return enum_for(:each_link, **options) unless block_given?
+
+      cursor = nil
+      loop do
+        page = links(**options, cursor: cursor)
+        page.each { |link| yield link }
+        break unless page.more?
+
+        cursor = page.cursor
+      end
     end
 
     def search_links(query: nil, url: nil, limit: nil, tag: nil, status: nil)
-      request(:get, "/api/link/search", query: {
+      body = request(:get, "/api/link/search", query: {
         q: query, url: url, limit: limit, tag: tag, status: status
       })
+
+      link_page(body)
     end
 
-    def tags = request(:get, "/api/link/tags")
+    def tags
+      Array(request(:get, "/api/link/tags")).map { |tag| Tag.from_response(tag) }
+    end
 
     def check_links(cursor: nil, limit: 6, timeout: 6)
-      request(:post, "/api/link/check", body: {
-        cursor: cursor, limit: limit, timeout: timeout
+      body = request(:post, "/api/link/check", body: {
+        "cursor" => cursor, "limit" => limit, "timeout" => timeout
       }.compact)
+
+      page(body, "results") { |result| Keys.underscore_keys(result) }
     end
 
     private
 
+    def link_payload(attributes)
+      unknown = attributes.keys - LINK_ATTRIBUTES
+      raise ArgumentError, "unknown link attributes: #{unknown.join(", ")}" if unknown.any?
+
+      payload = attributes.compact
+      expires_at = payload.delete(:expires_at)
+      payload[:expiration] = unix_timestamp(expires_at) unless expires_at.nil?
+
+      Keys.camelize_keys(payload)
+    end
+
+    def unix_timestamp(value)
+      return value.to_i if value.is_a?(Numeric)
+      return value.to_time.to_i if value.respond_to?(:to_time)
+
+      raise ArgumentError, "expires_at must be a Time or a unix timestamp"
+    end
+
+    def build_link(body) = Link.from_response(body, base_url: @base_url)
+
+    def link_page(body) = page(body, "links") { |link| build_link(link) }
+
+    def page(body, key, &build)
+      records, cursor, complete = case body
+                                  when Array then [body, nil, true]
+                                  when Hash then [Array(body[key]), body["cursor"], body.fetch("list_complete", true)]
+                                  else [[], nil, true]
+                                  end
+
+      Page.new(records: records.map(&build), cursor: cursor, complete: complete)
+    end
+
     def request(method, path, query: nil, body: nil)
       uri = URI("#{@base_url}#{path}")
       params = query&.compact
@@ -69,7 +143,15 @@ module Sink
       http_request = REQUEST_CLASSES.fetch(method).new(uri, headers)
       http_request.body = JSON.generate(body) if body
 
-      parse_response(perform_request(uri, http_request))
+      parse_response(dispatch(uri, http_request))
+    end
+
+    def dispatch(uri, http_request)
+      perform_request(uri, http_request)
+    rescue *TIMEOUT_ERRORS => error
+      raise TimeoutError.new("#{uri.host} timed out: #{error.message}")
+    rescue *CONNECTION_ERRORS => error
+      raise ConnectionError.new("#{uri.host} is unreachable: #{error.message}")
     end
 
     def perform_request(uri, request)
@@ -88,11 +170,16 @@ module Sink
       body = parse_body(response.body)
       return body if response.is_a?(Net::HTTPSuccess)
 
-      message = if body.is_a?(Hash)
-                  body["message"] || body["statusMessage"]
-                end
-      message ||= "HTTP #{response.code} #{response.message}"
-      raise Error.new(status: response.code.to_i, message: message, body: body)
+      message = error_message(body) || "HTTP #{response.code} #{response.message}"
+      raise Error.for(status: response.code.to_i, message: message, body: body)
+    end
+
+    def error_message(body)
+      return nil unless body.is_a?(Hash)
+
+      %w[message statusMessage statusText].filter_map { |key| body[key] }
+                                         .map { |value| value.to_s.strip }
+                                         .find { |value| !value.empty? }
     end
 
     def parse_body(body)

data/lib/sink/error.rb

@@ -4,10 +4,41 @@ module Sink
   class Error < StandardError
     attr_reader :status, :body
 
-    def initialize(status:, message:, body: nil)
+    def self.for(status:, message:, body: nil)
+      klass = STATUS_ERRORS[status] || (status.to_i >= 500 ? ServerError : self)
+      klass.new(message, status: status, body: body)
+    end
+
+    def initialize(message = nil, status: nil, body: nil)
       @status = status
       @body = body
       super(message)
     end
+
+    def data = body.is_a?(Hash) ? body["data"] : nil
+  end
+
+  class ValidationError < Error; end
+  class Unauthorized < Error; end
+  class Forbidden < Error; end
+  class NotFound < Error; end
+  class Conflict < Error; end
+  class StorageNotReady < Error; end
+  class RateLimited < Error; end
+  class ServerError < Error; end
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+
+  class Error
+    STATUS_ERRORS = {
+      400 => ValidationError,
+      401 => Unauthorized,
+      403 => Forbidden,
+      404 => NotFound,
+      409 => Conflict,
+      422 => ValidationError,
+      423 => StorageNotReady,
+      429 => RateLimited
+    }.freeze
   end
 end

data/lib/sink/keys.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sink
+  module Keys
+    module_function
+
+    def underscore(key)
+      key.to_s
+         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+         .to_sym
+    end
+
+    def camelize(key)
+      head, *tail = key.to_s.split("_")
+      [head, *tail.map(&:capitalize)].join
+    end
+
+    # Sink payloads are flat, so nested hashes such as `geo` keep their original
+    # keys (country codes) instead of being converted to snake_case.
+    def underscore_keys(hash)
+      hash.to_h { |key, value| [underscore(key), value] }
+    end
+
+    def camelize_keys(hash)
+      hash.to_h { |key, value| [camelize(key), value] }
+    end
+  end
+end

data/lib/sink/link.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Sink
+  class Link
+    ATTRIBUTES = %i[
+      id url slug comment title description image apple google password
+      cloaking redirect_with_query unsafe geo tags expiration
+      created_at updated_at short_link status
+    ].freeze
+
+    attr_reader :attributes
+
+    # The API only builds `shortLink` for write endpoints, from the protocol and
+    # host of the request, so `base_url` reproduces it for the read endpoints.
+    def self.from_response(body, base_url: nil)
+      return nil unless body.is_a?(Hash)
+
+      link = body["link"].is_a?(Hash) ? body["link"] : body
+      attributes = Keys.underscore_keys(link)
+      attributes[:status] = body["status"] if body.key?("status")
+      attributes[:short_link] = body["shortLink"] ||
+                                (base_url && attributes[:slug] && "#{base_url}/#{attributes[:slug]}")
+
+      new(attributes.compact)
+    end
+
+    def initialize(attributes)
+      @attributes = attributes.freeze
+    end
+
+    %i[id url slug comment title description image apple google password short_link status].each do |name|
+      define_method(name) { @attributes[name] }
+    end
+
+    def tags = @attributes[:tags] || []
+
+    def geo = @attributes[:geo] || {}
+
+    def expiration = @attributes[:expiration]
+
+    def created_at = time(:created_at)
+
+    def updated_at = time(:updated_at)
+
+    def expires_at = time(:expiration)
+
+    def cloaking? = !!@attributes[:cloaking]
+
+    def unsafe? = !!@attributes[:unsafe]
+
+    def redirect_with_query? = !!@attributes[:redirect_with_query]
+
+    def expired? = !expiration.nil? && expiration <= Time.now.to_i
+
+    def created? = status == "created"
+
+    def existing? = status == "existing"
+
+    def [](key) = @attributes[key.to_sym]
+
+    def to_h = @attributes.dup
+
+    def as_json(*) = to_h
+
+    def ==(other) = other.is_a?(Link) && other.attributes == @attributes
+    alias eql? ==
+
+    def hash = @attributes.hash
+
+    def inspect = "#<#{self.class} slug=#{slug.inspect} url=#{url.inspect}>"
+
+    private
+
+    def time(key)
+      value = @attributes[key]
+      Time.at(value).utc if value
+    end
+  end
+end

data/lib/sink/page.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sink
+  class Page
+    include Enumerable
+
+    attr_reader :records, :cursor
+
+    def initialize(records:, cursor: nil, complete: true)
+      @records = records.freeze
+      @cursor = cursor
+      @complete = complete
+    end
+
+    def each(&) = @records.each(&)
+
+    def complete? = !!@complete
+
+    def more? = !complete? && !cursor.nil?
+
+    def size = @records.size
+    alias length size
+
+    def empty? = @records.empty?
+
+    def [](index) = @records[index]
+
+    def to_a = @records.dup
+
+    def inspect = "#<#{self.class} size=#{size} cursor=#{cursor.inspect} complete=#{complete?}>"
+  end
+end

data/lib/sink/tag.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sink
+  Tag = Data.define(:name, :count) do
+    def self.from_response(body)
+      return new(name: body.to_s, count: nil) unless body.is_a?(Hash)
+
+      new(name: body["name"], count: body["count"])
+    end
+
+    def to_s = name.to_s
+  end
+end

data/lib/sink/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sink
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

data/lib/sink.rb

@@ -2,6 +2,10 @@
 
 require_relative "sink/version"
 require_relative "sink/error"
+require_relative "sink/keys"
+require_relative "sink/link"
+require_relative "sink/page"
+require_relative "sink/tag"
 require_relative "sink/client"
 require "thread"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sink-cool
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Sink Ruby contributors
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov_json_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: A lightweight Ruby client for managing links with the Sink URL shortener
   API.
 executables: []
@@ -50,6 +78,10 @@ files:
 - lib/sink.rb
 - lib/sink/client.rb
 - lib/sink/error.rb
+- lib/sink/keys.rb
+- lib/sink/link.rb
+- lib/sink/page.rb
+- lib/sink/tag.rb
 - lib/sink/version.rb
 homepage: https://docs.sink.cool/api/
 licenses: