sink-cool 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a00d2c68180f646548d25323730f7e93b9ba05304714a2a00964cc7d3891b747
+  data.tar.gz: 3f5976058e5efe20ffbdc8b5abbc189c5419a56881584b17bb51cf8fa37d5e52
+SHA512:
+  metadata.gz: f8265250d9c8a378c24e2ea0da1fd811caf2d09f81dbf08950741c0b3dbf297013dd25fbd701607588c4262fa1fea39161a92e72b91d48dbd10b314b7d8047a5
+  data.tar.gz: 2af5d5bf19381bbd9ef3708f2f6621f9c076c7d4cb53da6255466d36f176e027e5d2655204116d487f58d0792b155a6b5f50e459b7a4cb09be3952159596280c

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+### Added
+
+- GitHub Actions workflows for CI and trusted publishing to RubyGems.org.
+- MIT License.
+- RubyGems project metadata.
+
+### Changed
+
+- Require Ruby 3.3 or newer, matching the tested versions.
+- Publish version tags to RubyGems.org, GitHub Packages, and GitHub Releases after running the full Ruby version matrix.
+- Make global client initialization thread-safe.
+- Isolate HTTP transport in tests without patching `Net::HTTP` globally.
+
+## 0.1.0 - 2026-07-23
+
+### Added
+
+- Global configuration for the Sink base URL, site token, and HTTP timeouts.
+- Client methods for authentication, link management, search, tags, and link checks.
+- Structured `Sink::Error` exceptions for unsuccessful API responses.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sink-cool contributors
+
+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,128 @@
+# sink-cool
+
+Ruby client for the [Sink](https://sink.cool/) URL shortener API.
+
+Requires Ruby 3.3 or newer.
+
+## Installation
+
+Add the gem to your bundle:
+
+```bash
+bundle add sink-cool
+```
+
+Or install it directly:
+
+```bash
+gem install sink-cool
+```
+
+## Configuration
+
+Create an initializer such as `config/initializers/sink.rb`:
+
+```ruby
+require "sink-cool"
+
+Sink.configure do |config|
+  config.base_url = ENV.fetch("SINK_BASE_URL")
+  config.token = ENV.fetch("SINK_TOKEN")
+end
+```
+
+Use HTTPS in production so the bearer token is encrypted in transit.
+
+Optional HTTP timeouts:
+
+```ruby
+Sink.configure do |config|
+  config.base_url = ENV.fetch("SINK_BASE_URL")
+  config.token = ENV.fetch("SINK_TOKEN")
+  config.open_timeout = 5
+  config.read_timeout = 30
+end
+```
+
+You can also create an independent client:
+
+```ruby
+client = Sink::Client.new(
+  base_url: "https://sink.example.com",
+  token: "site-token"
+)
+```
+
+## Usage
+
+```ruby
+client = Sink.client
+
+client.verify
+
+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"]
+)
+
+client.upsert_link(url: "https://example.com", slug: "example")
+client.link("example")
+client.links(limit: 20, sort: "newest", status: "active")
+client.search_links(query: "example", tag: "articles")
+client.tags
+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`.
+
+## Errors
+
+Non-successful responses raise `Sink::Error`:
+
+```ruby
+begin
+  Sink.client.link("missing")
+rescue Sink::Error => error
+  error.status
+  error.message
+  error.body
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+gem build sink-cool.gemspec
+```
+
+See the [Sink API documentation](https://docs.sink.cool/api/) for endpoint and
+payload details.
+
+## Releasing
+
+Configure a trusted publisher for this repository and `release.yml` on
+RubyGems.org. Update `Sink::VERSION` and the matching `CHANGELOG.md` section,
+then push a matching version tag:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The release workflow tests Ruby 3.3, 3.4, and 4.0 before publishing to
+RubyGems.org, GitHub Packages, and GitHub Releases.
+
+## License
+
+This gem is available under the [MIT License](LICENSE.txt).

data/lib/sink/client.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Sink
+  class Client
+    REQUEST_CLASSES = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put
+    }.freeze
+
+    def initialize(base_url:, token:, open_timeout: 5, read_timeout: 30)
+      @base_url = validate_base_url(base_url)
+      @token = token.to_s
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      raise ArgumentError, "token is required" if @token.empty?
+    end
+
+    def verify = request(:get, "/api/verify")
+
+    def create_link(attributes) = request(:post, "/api/link/create", body: attributes)
+
+    def edit_link(attributes) = request(:put, "/api/link/edit", body: attributes)
+
+    def upsert_link(attributes) = request(:post, "/api/link/upsert", body: attributes)
+
+    def delete_link(slug) = request(:post, "/api/link/delete", body: { slug: slug })
+
+    def link(slug) = 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: {
+        limit: limit, cursor: cursor, sort: sort, tag: tag, status: status
+      })
+    end
+
+    def search_links(query: nil, url: nil, limit: nil, tag: nil, status: nil)
+      request(:get, "/api/link/search", query: {
+        q: query, url: url, limit: limit, tag: tag, status: status
+      })
+    end
+
+    def tags = request(:get, "/api/link/tags")
+
+    def check_links(cursor: nil, limit: 6, timeout: 6)
+      request(:post, "/api/link/check", body: {
+        cursor: cursor, limit: limit, timeout: timeout
+      }.compact)
+    end
+
+    private
+
+    def request(method, path, query: nil, body: nil)
+      uri = URI("#{@base_url}#{path}")
+      params = query&.compact
+      uri.query = URI.encode_www_form(params) if params&.any?
+
+      headers = {
+        "Authorization" => "Bearer #{@token}",
+        "Accept" => "application/json",
+        "User-Agent" => "sink-cool/#{Sink::VERSION}"
+      }
+      headers["Content-Type"] = "application/json" if body
+
+      http_request = REQUEST_CLASSES.fetch(method).new(uri, headers)
+      http_request.body = JSON.generate(body) if body
+
+      parse_response(perform_request(uri, http_request))
+    end
+
+    def perform_request(uri, request)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) { |http| http.request(request) }
+    end
+
+    def parse_response(response)
+      return nil if response.code.to_i == 204
+
+      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)
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def validate_base_url(base_url)
+      uri = URI(base_url.to_s)
+      raise ArgumentError, "base_url must be an HTTP(S) URL" unless %w[http https].include?(uri.scheme) && uri.host
+
+      base_url.to_s.sub(%r{/+\z}, "")
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url must be an HTTP(S) URL"
+    end
+  end
+end

data/lib/sink/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sink
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(status:, message:, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end

data/lib/sink/version.rb

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

data/lib/sink-cool.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sink"

data/lib/sink.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "sink/version"
+require_relative "sink/error"
+require_relative "sink/client"
+require "thread"
+
+module Sink
+  Configuration = Struct.new(:base_url, :token, :open_timeout, :read_timeout, keyword_init: true)
+  CLIENT_MUTEX = Mutex.new
+
+  class << self
+    def configure
+      configured = configuration.dup
+      yield configured
+
+      CLIENT_MUTEX.synchronize do
+        @configuration = configured
+        @client = nil
+      end
+
+      configured
+    end
+
+    def configuration
+      return @configuration if @configuration
+
+      CLIENT_MUTEX.synchronize do
+        @configuration ||= Configuration.new(open_timeout: 5, read_timeout: 30)
+      end
+    end
+
+    def client
+      return @client if @client
+
+      CLIENT_MUTEX.synchronize { @client ||= Client.new(**configuration.to_h) }
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: sink-cool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sink Ruby contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.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: A lightweight Ruby client for managing links with the Sink URL shortener
+  API.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/sink-cool.rb
+- lib/sink.rb
+- lib/sink/client.rb
+- lib/sink/error.rb
+- lib/sink/version.rb
+homepage: https://docs.sink.cool/api/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.sink.cool/api/
+  source_code_uri: https://github.com/7a6163/sink-cool
+  changelog_uri: https://github.com/7a6163/sink-cool/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Ruby client for the Sink URL shortener API
+test_files: []