superthread 0.7.2

data/lib/superthread/resources/pages.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for page (document) operations.
+    #
+    # Provides methods for creating, updating, and managing pages
+    # (documents, wikis) via the Superthread API.
+    class Pages < Base
+      # Lists all pages in a workspace.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String, nil] optional space identifier to filter by
+      # @param archived [Boolean, nil] when true, includes archived pages
+      # @param updated_recently [Boolean, nil] when true, returns only recently updated pages
+      # @return [Superthread::Objects::Collection<Superthread::Models::Page>] the pages in the workspace
+      def list(workspace_id, space_id: nil, archived: nil, updated_recently: nil)
+        ws = safe_id("workspace_id", workspace_id)
+        params = compact_params(project_id: space_id, archived: archived, updated_recently: updated_recently)
+        get_collection("/#{ws}/pages", params: params,
+          item_class: Models::Page, items_key: :pages)
+      end
+
+      # Gets a specific page.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier
+      # @return [Superthread::Models::Page] the page with all attributes
+      def find(workspace_id, page_id)
+        ws = safe_id("workspace_id", workspace_id)
+        page = safe_id("page_id", page_id)
+        get_object("/#{ws}/pages/#{page}",
+          object_class: Models::Page, unwrap_key: :page)
+      end
+
+      # Creates a new page in a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier
+      # @param params [Hash{Symbol => Object}] page parameters
+      # @option params [String] :title the page title
+      # @option params [String] :content the page content as HTML
+      # @option params [Hash{Symbol => Object}] :schema the content schema for structured content
+      # @option params [String] :parent_page_id the parent page identifier for nesting
+      # @return [Superthread::Models::Page] the created page
+      def create(workspace_id, space_id:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(project_id: space_id, **params)
+        post_object("/#{ws}/pages", body: body,
+          object_class: Models::Page, unwrap_key: :page)
+      end
+
+      # Updates a page's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :title the new page title
+      # @option params [String] :content the new page content as HTML
+      # @option params [Boolean] :archived whether the page is archived
+      # @option params [String] :parent_page_id the new parent page identifier
+      # @return [Superthread::Models::Page] the updated page
+      def update(workspace_id, page_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        page = safe_id("page_id", page_id)
+        patch_object("/#{ws}/pages/#{page}", body: compact_params(**params),
+          object_class: Models::Page, unwrap_key: :page)
+      end
+
+      # Duplicates a page to a destination space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier to duplicate
+      # @param space_id [String] the destination space identifier
+      # @param params [Hash{Symbol => Object}] optional duplication parameters
+      # @option params [String] :title the title for the duplicated page (defaults to original)
+      # @option params [String] :parent_page_id the parent page identifier in the destination
+      # @option params [Integer] :position the position index among sibling pages
+      # @return [Superthread::Models::Page] the duplicated page
+      def duplicate(workspace_id, page_id, space_id:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        page = safe_id("page_id", page_id)
+        body = compact_params(project_id: space_id, **params)
+        post_object("/#{ws}/pages/#{page}/copy", body: body,
+          object_class: Models::Page, unwrap_key: :page)
+      end
+
+      # Archives a page (soft delete).
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier to archive
+      # @return [Superthread::Models::Page] the archived page
+      def archive(workspace_id, page_id)
+        update(workspace_id, page_id, archived: true)
+      end
+
+      # Deletes a page permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param page_id [String] the page identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def destroy(workspace_id, page_id)
+        ws = safe_id("workspace_id", workspace_id)
+        page = safe_id("page_id", page_id)
+        http_delete("/#{ws}/pages/#{page}")
+        success_response
+      end
+    end
+  end
+end

data/lib/superthread/resources/projects.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for project (epic/roadmap item) operations.
+    #
+    # Provides methods for creating, updating, and managing projects
+    # (epics) and their linked cards via the Superthread API.
+    class Projects < Base
+      # Lists all roadmap projects (epics) in a workspace.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @return [Superthread::Objects::Collection<Superthread::Models::Project>] the projects in the workspace
+      # @note The API returns epics nested within lists (status columns).
+      #   This method flattens them into a single collection.
+      def list(workspace_id)
+        ws = safe_id("workspace_id", workspace_id)
+        data = http_get("/#{ws}/epics")
+
+        # Epics are nested inside each list - flatten them
+        epics = (data[:lists] || []).flat_map { |list| list[:epics] || [] }
+
+        Superthread::Objects::Collection.from_response(
+          {epics: epics},
+          key: :epics,
+          item_class: Models::Project
+        )
+      end
+
+      # Gets a specific project.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param project_id [String] the project identifier (maps to epic_id in API)
+      # @return [Superthread::Models::Project] the project with all attributes
+      def find(workspace_id, project_id)
+        ws = safe_id("workspace_id", workspace_id)
+        proj = safe_id("project_id", project_id)
+        get_object("/#{ws}/epics/#{proj}",
+          object_class: Models::Project, unwrap_key: :epic)
+      end
+
+      # Creates a new project (epic) on the roadmap.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param title [String] the project title
+      # @param list_id [String] the list identifier (status column) for the project
+      # @param params [Hash{Symbol => Object}] optional project parameters
+      # @option params [String] :content the project description content
+      # @option params [Integer] :start_date the start date as Unix timestamp
+      # @option params [Integer] :due_date the due date as Unix timestamp
+      # @return [Superthread::Models::Project] the created project
+      def create(workspace_id, title:, list_id:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(title: title, list_id: list_id, **params)
+        post_object("/#{ws}/epics", body: body,
+          object_class: Models::Project, unwrap_key: :epic)
+      end
+
+      # Updates a project's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param project_id [String] the project identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :title the new project title
+      # @option params [String] :content the new project description
+      # @option params [String] :list_id the new list identifier (status column)
+      # @option params [Integer] :start_date the new start date as Unix timestamp
+      # @option params [Integer] :due_date the new due date as Unix timestamp
+      # @return [Superthread::Models::Project] the updated project
+      def update(workspace_id, project_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        proj = safe_id("project_id", project_id)
+        patch_object("/#{ws}/epics/#{proj}", body: compact_params(**params),
+          object_class: Models::Project, unwrap_key: :epic)
+      end
+
+      # Deletes a project permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param project_id [String] the project identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def destroy(workspace_id, project_id)
+        ws = safe_id("workspace_id", workspace_id)
+        proj = safe_id("project_id", project_id)
+        http_delete("/#{ws}/epics/#{proj}")
+        success_response
+      end
+
+      # Links a card to a project (epic).
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param project_id [String] the project identifier
+      # @param card_id [String] the card identifier to link
+      # @return [Superthread::Object] the link result
+      def add_card(workspace_id, project_id, card_id)
+        ws = safe_id("workspace_id", workspace_id)
+        proj = safe_id("project_id", project_id)
+        card = safe_id("card_id", card_id)
+        post_object("/#{ws}/epics/#{proj}/cards/#{card}")
+      end
+
+      # Removes a card from a project (epic).
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param project_id [String] the project identifier
+      # @param card_id [String] the card identifier to remove
+      # @return [Superthread::Object] a response object with success: true
+      def remove_card(workspace_id, project_id, card_id)
+        ws = safe_id("workspace_id", workspace_id)
+        proj = safe_id("project_id", project_id)
+        card = safe_id("card_id", card_id)
+        http_delete("/#{ws}/epics/#{proj}/cards/#{card}")
+        success_response
+      end
+    end
+  end
+end

data/lib/superthread/resources/search.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for search operations.
+    #
+    # Provides methods for searching across workspace entities
+    # (cards, pages, boards, etc.) via the Superthread API.
+    class Search < Base
+      # Searches across workspace entities.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param query [String] the search query string
+      # @param params [Hash{Symbol => Object}] optional search parameters
+      # @option params [String] :field the field to search (title, content)
+      # @option params [Array<String>] :types entity types to include (board, card, page, etc.)
+      # @option params [Array<String>] :statuses status values to filter by
+      # @option params [String] :space_id the space identifier to filter by
+      # @option params [Boolean] :archived when true, includes archived entities
+      # @option params [Boolean] :grouped when true, groups results by type (default: false)
+      # @option params [String] :cursor the pagination cursor for next page
+      # @return [Superthread::Objects::Collection] the search results
+      def query(workspace_id, query:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        # Default grouped to false so results come in a flat array
+        # Use || instead of fetch because CLI may pass grouped: nil explicitly
+        grouped = params[:grouped].nil? ? false : params[:grouped]
+        search_params = compact_params(
+          query: query,
+          project_id: params[:space_id],
+          grouped: grouped,
+          **params.except(:space_id, :grouped)
+        )
+        response = http_get("/#{ws}/search", params: search_params)
+
+        # Unwrap results - each item is {"card": {...}} or {"board": {...}}, etc.
+        results = (response[:results] || []).map do |item|
+          result_type, data = item.first
+          data.merge(result_type: result_type.to_s)
+        end
+
+        Objects::Collection.from_response(results)
+      end
+    end
+  end
+end

data/lib/superthread/resources/spaces.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for space operations.
+    #
+    # Provides methods for creating, updating, and managing spaces
+    # and their members via the Superthread API.
+    class Spaces < Base
+      # Lists all spaces in a workspace.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @return [Superthread::Objects::Collection<Superthread::Models::Space>] the spaces in the workspace
+      def list(workspace_id)
+        ws = safe_id("workspace_id", workspace_id)
+        get_collection("/#{ws}/projects",
+          item_class: Models::Space, items_key: :projects)
+      end
+
+      # Gets a specific space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier (maps to project_id in API)
+      # @return [Superthread::Models::Space] the space with all attributes
+      def find(workspace_id, space_id)
+        ws = safe_id("workspace_id", workspace_id)
+        space = safe_id("space_id", space_id)
+        get_object("/#{ws}/projects/#{space}",
+          object_class: Models::Space, unwrap_key: :project)
+      end
+
+      # Creates a new space in the workspace.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param title [String] the space title
+      # @param params [Hash{Symbol => Object}] optional space parameters
+      # @option params [String] :description the space description
+      # @option params [String] :icon the space icon identifier
+      # @return [Superthread::Models::Space] the created space
+      def create(workspace_id, title:, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(title: title, **params)
+        post_object("/#{ws}/projects", body: body,
+          object_class: Models::Space, unwrap_key: :project)
+      end
+
+      # Updates a space's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :title the new space title
+      # @option params [String] :description the new space description
+      # @option params [String] :icon the new space icon identifier
+      # @return [Superthread::Models::Space] the updated space
+      def update(workspace_id, space_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        space = safe_id("space_id", space_id)
+        patch_object("/#{ws}/projects/#{space}", body: compact_params(**params),
+          object_class: Models::Space, unwrap_key: :project)
+      end
+
+      # Deletes a space permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def destroy(workspace_id, space_id)
+        ws = safe_id("workspace_id", workspace_id)
+        space = safe_id("space_id", space_id)
+        http_delete("/#{ws}/projects/#{space}")
+        success_response
+      end
+
+      # Adds a member to a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier
+      # @param user_id [String] the user identifier to add as a member
+      # @param role [String] the member role (admin, member, viewer)
+      # @return [Superthread::Object] the membership result
+      def add_member(workspace_id, space_id, user_id:, role: "member")
+        ws = safe_id("workspace_id", workspace_id)
+        space = safe_id("space_id", space_id)
+        body = {members: [{user_id: user_id, role: role}]}
+        post_object("/#{ws}/projects/#{space}/members", body: body)
+      end
+
+      # Removes a member from a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier
+      # @param user_id [String] the user identifier to remove
+      # @return [Superthread::Object] a response object with success: true
+      def remove_member(workspace_id, space_id, user_id)
+        ws = safe_id("workspace_id", workspace_id)
+        space = safe_id("space_id", space_id)
+        user = safe_id("user_id", user_id)
+        http_delete("/#{ws}/projects/#{space}/members/#{user}")
+        success_response
+      end
+    end
+  end
+end

data/lib/superthread/resources/sprints.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for sprint operations.
+    #
+    # Provides methods for listing and retrieving sprints
+    # via the Superthread API.
+    class Sprints < Base
+      # Lists all sprints in a space.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param space_id [String] the space identifier to list sprints from
+      # @return [Superthread::Objects::Collection<Superthread::Models::Sprint>] the sprints in the space
+      def list(workspace_id, space_id:)
+        ws = safe_id("workspace_id", workspace_id)
+        params = compact_params(project_id: space_id)
+        get_collection("/#{ws}/sprints", params: params,
+          item_class: Models::Sprint, items_key: :sprints)
+      end
+
+      # Gets a specific sprint with its available lists.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param sprint_id [String] the sprint identifier
+      # @param space_id [String] the space identifier (required by the API)
+      # @return [Superthread::Models::Sprint] the sprint with available lists
+      def find(workspace_id, sprint_id, space_id:)
+        ws = safe_id("workspace_id", workspace_id)
+        sprint = safe_id("sprint_id", sprint_id)
+        params = compact_params(project_id: space_id)
+        get_object("/#{ws}/sprints/#{sprint}", params: params,
+          object_class: Models::Sprint, unwrap_key: :sprint)
+      end
+    end
+  end
+end

data/lib/superthread/resources/tags.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for tag operations.
+    #
+    # Provides methods for creating, updating, and deleting tags
+    # via the Superthread API.
+    class Tags < Base
+      # Creates a new tag in the workspace.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param name [String] the tag name
+      # @param color [String] the tag color as hex string (e.g., "#FF5733")
+      # @param space_id [String, nil] optional space identifier to scope the tag
+      # @return [Superthread::Models::Tag] the created tag
+      def create(workspace_id, name:, color:, space_id: nil)
+        ws = safe_id("workspace_id", workspace_id)
+        body = compact_params(name: name, color: color, project_id: space_id)
+        post_object("/#{ws}/tags", body: body,
+          object_class: Models::Tag, unwrap_key: :tag)
+      end
+
+      # Updates a tag's attributes.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param tag_id [String] the tag identifier
+      # @param params [Hash{Symbol => Object}] the attributes to update
+      # @option params [String] :name the new tag name
+      # @option params [String] :color the new tag color as hex string
+      # @return [Superthread::Models::Tag] the updated tag
+      def update(workspace_id, tag_id, **params)
+        ws = safe_id("workspace_id", workspace_id)
+        tag = safe_id("tag_id", tag_id)
+        patch_object("/#{ws}/tags/#{tag}", body: compact_params(**params),
+          object_class: Models::Tag, unwrap_key: :tag)
+      end
+
+      # Deletes a tag permanently.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @param tag_id [String] the tag identifier to delete
+      # @return [Superthread::Object] a response object with success: true
+      def destroy(workspace_id, tag_id)
+        ws = safe_id("workspace_id", workspace_id)
+        tag = safe_id("tag_id", tag_id)
+        http_delete("/#{ws}/tags/#{tag}")
+        success_response
+      end
+    end
+  end
+end

data/lib/superthread/resources/users.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Resources
+    # API resource for user operations.
+    #
+    # Provides methods for retrieving user information and
+    # listing workspace members via the Superthread API.
+    class Users < Base
+      # Gets the current authenticated user's account information.
+      #
+      # @return [Superthread::Models::User] the current user's profile
+      def me
+        get_object("/users/me", object_class: Models::User, unwrap_key: :user)
+      end
+
+      # Gets workspace members.
+      #
+      # @param workspace_id [String] the workspace identifier
+      # @return [Superthread::Objects::Collection<Superthread::Models::User>] the workspace members
+      # @note The API uses /teams/:id/members but we use workspace terminology.
+      def members(workspace_id)
+        ws = safe_id("workspace_id", workspace_id)
+        get_collection("/teams/#{ws}/members",
+          item_class: Models::User, items_key: :members)
+      end
+    end
+  end
+end

data/lib/superthread/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Superthread
+  # Current version of the Superthread gem.
+  VERSION = "0.7.2"
+end

data/lib/superthread/version_checker.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "fileutils"
+
+module Superthread
+  # Checks for newer versions of the Superthread CLI.
+  #
+  # Uses the GitHub Releases API to find the latest version and caches
+  # the result to avoid repeated network requests. Designed to never
+  # interrupt or slow down normal CLI usage.
+  #
+  # @example Check for updates
+  #   Superthread::VersionChecker.check_if_stale!
+  #   if (notice = Superthread::VersionChecker.update_notice)
+  #     $stderr.puts notice
+  #   end
+  #
+  # @example Force check (bypass cache TTL)
+  #   latest = Superthread::VersionChecker.check!
+  module VersionChecker
+    # GitHub API endpoint for the latest release.
+    RELEASES_URL = "https://api.github.com/repos/steveclarke/superthread/releases/latest"
+
+    # How long to cache the version check result (24 hours).
+    CACHE_TTL = 86_400
+
+    # HTTP connect timeout in seconds.
+    CONNECT_TIMEOUT = 3
+
+    # HTTP read timeout in seconds.
+    READ_TIMEOUT = 5
+
+    module_function
+
+    # Returns a formatted update notice if a newer version is available.
+    #
+    # Reads from cache only — does not make network requests.
+    # Returns nil if no update is available, cache is missing, or
+    # update checks are disabled.
+    #
+    # @return [String, nil] update message or nil
+    def update_notice
+      return nil if disabled?
+
+      cached = read_cache
+      return nil unless cached
+
+      latest = cached[:latest_version]
+      return nil unless latest
+      return nil unless newer?(latest)
+
+      current = Superthread::VERSION
+      "\n" \
+        "  Update available: #{current} \u2192 #{latest}\n" \
+        "  Run: brew upgrade superthread\n"
+    end
+
+    # Fetches the latest version from GitHub and updates the cache.
+    #
+    # Always makes a network request regardless of cache freshness.
+    # Returns nil silently on any error (network, parse, etc.).
+    #
+    # @return [String, nil] the latest version string, or nil on failure
+    def check!
+      return nil if disabled?
+
+      version = fetch_latest_version
+      write_cache(version) if version
+      version
+    rescue
+      nil
+    end
+
+    # Fetches the latest version only if the cache is stale.
+    #
+    # If the cache is fresh (less than {CACHE_TTL} old), does nothing.
+    # This is the method to call on every CLI invocation — it's
+    # effectively free when the cache is warm.
+    #
+    # @return [String, nil] the latest version string, or nil
+    def check_if_stale!
+      return nil if disabled?
+
+      cached = read_cache
+      if cached && (Time.now.to_i - cached[:checked_at].to_i) < CACHE_TTL
+        return cached[:latest_version]
+      end
+
+      check!
+    rescue
+      nil
+    end
+
+    # Whether version checking is disabled via environment variable.
+    #
+    # @return [Boolean] true if SUPERTHREAD_NO_UPDATE_CHECK is set
+    def disabled?
+      ENV.key?("SUPERTHREAD_NO_UPDATE_CHECK")
+    end
+
+    # Compares a version string against the current version.
+    #
+    # @param version [String] the version to compare
+    # @return [Boolean] true if the given version is newer
+    def newer?(version)
+      Gem::Version.new(version) > Gem::Version.new(Superthread::VERSION)
+    rescue ArgumentError
+      false
+    end
+
+    # Returns the path to the version check cache file.
+    #
+    # @return [String] absolute path to version_check.json
+    def cache_path
+      File.join(
+        ENV.fetch("XDG_STATE_HOME", File.expand_path("~/.local/state")),
+        "superthread",
+        "version_check.json"
+      )
+    end
+
+    # Reads the cached version check result.
+    #
+    # @return [Hash{Symbol => Object}, nil] cached data or nil
+    def read_cache
+      return nil unless File.exist?(cache_path)
+
+      data = JSON.parse(File.read(cache_path), symbolize_names: true)
+      data if data.is_a?(Hash)
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    # Writes a version check result to the cache file.
+    #
+    # @param version [String] the latest version string
+    # @return [void]
+    def write_cache(version)
+      FileUtils.mkdir_p(File.dirname(cache_path))
+      File.write(cache_path, JSON.generate(
+        latest_version: version,
+        checked_at: Time.now.to_i
+      ))
+    rescue Errno::EACCES, Errno::ENOSPC
+      nil
+    end
+
+    # Fetches the latest version tag from GitHub Releases API.
+    #
+    # @return [String, nil] version string (without leading "v"), or nil
+    def fetch_latest_version
+      conn = Faraday.new(url: RELEASES_URL) do |f|
+        f.headers["Accept"] = "application/vnd.github+json"
+        f.options.timeout = READ_TIMEOUT
+        f.options.open_timeout = CONNECT_TIMEOUT
+        f.adapter Faraday.default_adapter
+      end
+
+      response = conn.get
+      return nil unless response.status == 200
+
+      data = JSON.parse(response.body, symbolize_names: true)
+      tag = data[:tag_name]
+      return nil unless tag
+
+      # Strip leading "v" (e.g., "v0.5.7" -> "0.5.7")
+      tag.sub(/\Av/, "")
+    rescue Faraday::Error, JSON::ParserError
+      nil
+    end
+  end
+end