heedkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d90db8da72e11a9058298022e35575c16bb5ddc99ed82e99f311cd337b017f36
+  data.tar.gz: c6bb8675fad6cba884df875a86617ad9fb2df24a822662fbf58ce20cc94632b4
+SHA512:
+  metadata.gz: 548f044f2276926ebe16960f0da8969dab328e9546edb392e6344dc208fbd56458034f0284585349b78a9b09a3d56ea2169a166bb35bdadd46081d808258ad8c
+  data.tar.gz: 4429b95f990e9065fc41569cc8b2fd59dcaf5d0bedb2d4533ddf401c2086d1103741b63b7f0c163c48f8a1577431229b12d03d6e3298ba8146bd14cb69e9f45f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeedKit
+
+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,57 @@
+# heedkit (Ruby / Rails SDK)
+
+Server-side SDK for [HeedKit](https://heedkit.com). Fetch a project's **public
+roadmap** and drive the **end-user feedback API** (identify / list / submit / vote /
+comment) from any Ruby or Rails app.
+
+```ruby
+gem "heedkit"
+```
+
+## Configure
+
+```ruby
+HeedKit.configure do |c|
+  c.project_key = ENV["HEEDKIT_PROJECT_KEY"]   # "fk_..."
+  c.endpoint    = "https://acme.heedkit.com"   # your HeedKit base URL
+end
+```
+
+## Roadmap
+
+```ruby
+roadmap = HeedKit.roadmap            # => HeedKit::Roadmap
+roadmap.project_name                    # "Acme Feedback"
+roadmap.each_column do |status, label, items|
+  puts "#{label}: #{items.map(&:title).join(', ')}"
+end
+```
+
+In **Rails**, a `heedkit` helper (the configured client) is available in controllers
+and views:
+
+```erb
+<% heedkit.roadmap.each_column do |status, label, items| %>
+  <h3><%= label %></h3>
+  <% items.each { |item| %><p><%= item.title %> · ▲ <%= item.vote_count %></p><% } %>
+<% end %>
+```
+
+## Feedback API
+
+```ruby
+fk = HeedKit.client
+user = fk.identify(external_id: "user-123", email: "ada@example.com")
+fk.submit(end_user_id: user["end_user_id"], title: "Dark mode", kind: "feature_request")
+fk.features(end_user_id: user["end_user_id"], sort: "top")
+fk.vote(feature_id, end_user_id: user["end_user_id"])
+fk.comment(feature_id, end_user_id: user["end_user_id"], body: "Yes please")
+```
+
+`identify` / `submit` / `features` / `vote` / `comment` authenticate with the project key
+via the `X-Project-Key` header; `roadmap` reads the public endpoint. All methods raise
+`HeedKit::Error` on a non-2xx response.
+
+## License
+
+MIT.

data/lib/heedkit/changelog.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "time"
+
+module HeedKit
+  # A single published changelog entry (release note). `body` is markdown; `published_at`
+  # is a Time (or nil).
+  ChangelogEntry = Struct.new(
+    :id, :title, :body, :category, :category_label, :published_at, keyword_init: true
+  ) do
+    def date = published_at
+  end
+
+  # A project's public changelog: published entries, newest first.
+  class Changelog
+    CATEGORY_LABELS = {
+      "new" => "New", "improved" => "Improved", "fixed" => "Fixed", "announcement" => "Announcement"
+    }.freeze
+
+    attr_reader :project_name, :theme, :entries
+
+    def self.from_payload(payload)
+      entries = (payload["entries"] || []).map do |e|
+        ChangelogEntry.new(
+          id: e["id"], title: e["title"], body: e["body"], category: e["category"],
+          category_label: e["category_label"] || CATEGORY_LABELS[e["category"]] || e["category"],
+          published_at: parse_time(e["published_at"])
+        )
+      end
+      new(project_name: payload["project_name"], theme: payload["theme"] || {}, entries: entries)
+    end
+
+    def self.parse_time(value)
+      return nil if value.to_s.empty?
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def initialize(project_name:, theme:, entries:)
+      @project_name = project_name
+      @theme = theme
+      @entries = entries
+    end
+
+    include Enumerable
+    def each(&block) = entries.each(&block)
+
+    def primary_color
+      theme["primary"] || "#0d9488"
+    end
+
+    def size = entries.size
+  end
+end

data/lib/heedkit/client.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module HeedKit
+  # Server-side client for the HeedKit API. Talks to the public roadmap endpoint
+  # and the end-user SDK endpoints (X-Project-Key auth).
+  class Client
+    DEFAULT_TIMEOUT = 5
+
+    attr_reader :project_key, :endpoint
+
+    def initialize(project_key:, endpoint:, timeout: DEFAULT_TIMEOUT)
+      raise ArgumentError, "project_key is required" if project_key.to_s.empty?
+      raise ArgumentError, "endpoint is required" if endpoint.to_s.empty?
+
+      @project_key = project_key
+      @endpoint = endpoint.to_s.chomp("/")
+      @timeout = timeout
+    end
+
+    # GET the public roadmap. Returns a HeedKit::Roadmap.
+    def roadmap
+      Roadmap.from_payload(get("/public/projects/#{project_key}/roadmap"))
+    end
+
+    # GET the public changelog. Returns a HeedKit::Changelog.
+    def changelog
+      Changelog.from_payload(get("/public/projects/#{project_key}/changelog"))
+    end
+
+    # POST /sdk/init — identify (find-or-create) an end-user. Returns the parsed body
+    # ({ "end_user_id" => ..., "project" => {...} }).
+    def identify(external_id: nil, email: nil, name: nil, avatar_url: nil, platform: nil)
+      sdk_post("/sdk/init", external_id:, email:, name:, avatar_url:, platform:)
+    end
+
+    # GET /sdk/features — public features plus the caller's own private submissions.
+    def features(end_user_id: nil, status: nil, kind: nil, sort: "top", cursor: nil)
+      query = { end_user_id:, status:, kind:, sort:, cursor: }.compact
+      sdk_get("/sdk/features", query)
+    end
+
+    # POST /sdk/features — submit a feature on behalf of an end-user.
+    def submit(end_user_id:, title:, description: nil, kind: "feature_request", tag: nil)
+      sdk_post("/sdk/features", end_user_id:, title:, description:, kind:, tag:)
+    end
+
+    # POST /sdk/features/:id/vote — toggle a vote.
+    def vote(feature_id, end_user_id:)
+      sdk_post("/sdk/features/#{feature_id}/vote", end_user_id:)
+    end
+
+    # POST /sdk/features/:id/comments — comment as an end-user.
+    def comment(feature_id, end_user_id:, body:)
+      sdk_post("/sdk/features/#{feature_id}/comments", end_user_id:, body:)
+    end
+
+    private
+
+    def sdk_get(path, query)
+      get(path, query:, headers: key_header)
+    end
+
+    def sdk_post(path, **body)
+      post(path, body: body.compact, headers: key_header)
+    end
+
+    def key_header
+      { "X-Project-Key" => project_key }
+    end
+
+    def get(path, query: {}, headers: {})
+      uri = build_uri(path, query)
+      request(Net::HTTP::Get.new(uri), uri, headers)
+    end
+
+    def post(path, body:, headers: {})
+      uri = build_uri(path)
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body)
+      request(req, uri, headers)
+    end
+
+    def build_uri(path, query = {})
+      uri = URI.parse("#{endpoint}#{path}")
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def request(req, uri, headers)
+      headers.each { |k, v| req[k] = v }
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      res = http.request(req)
+      unless res.code.to_i.between?(200, 299)
+        raise Error, "HeedKit API #{res.code} for #{uri.path}: #{res.body}"
+      end
+
+      res.body.to_s.empty? ? {} : JSON.parse(res.body)
+    rescue JSON::ParserError => e
+      raise Error, "Invalid JSON from HeedKit API: #{e.message}"
+    rescue SocketError, SystemCallError, IOError, Timeout::Error => e
+      # Wrap transport failures (connection refused, DNS, timeouts) in our own error
+      # type so callers only need to rescue HeedKit::Error.
+      raise Error, "HeedKit request to #{uri} failed: #{e.message}"
+    end
+  end
+end

data/lib/heedkit/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module HeedKit
+  # Exposes a `heedkit` accessor (the configured client) to controllers and views.
+  module Helper
+    def heedkit
+      HeedKit.client
+    end
+  end
+
+  class Railtie < ::Rails::Railtie
+    initializer "heedkit.helper" do
+      ActiveSupport.on_load(:action_controller) do
+        include HeedKit::Helper
+        helper HeedKit::Helper if respond_to?(:helper)
+      end
+    end
+  end
+end

data/lib/heedkit/roadmap.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module HeedKit
+  # A single roadmap item.
+  RoadmapItem = Struct.new(:id, :title, :description, :vote_count, :tag, keyword_init: true)
+
+  # The public roadmap for a project: ordered status columns, each a list of items.
+  class Roadmap
+    # Column order matches the product (Planned → In progress → Shipped).
+    STATUSES = %w[planned in_progress shipped].freeze
+    LABELS = { "planned" => "Planned", "in_progress" => "In progress", "shipped" => "Shipped" }.freeze
+
+    attr_reader :project_name, :theme, :columns
+
+    def self.from_payload(payload)
+      cols = (payload["columns"] || {}).transform_values do |items|
+        items.map do |i|
+          RoadmapItem.new(id: i["id"], title: i["title"], description: i["description"],
+                          vote_count: i["vote_count"], tag: i["tag"])
+        end
+      end
+      new(project_name: payload["project_name"], theme: payload["theme"] || {}, columns: cols)
+    end
+
+    def initialize(project_name:, theme:, columns:)
+      @project_name = project_name
+      @theme = theme
+      @columns = columns
+    end
+
+    def each_column
+      return enum_for(:each_column) unless block_given?
+
+      STATUSES.each { |status| yield status, LABELS[status], (columns[status] || []) }
+    end
+
+    def primary_color
+      theme["primary"] || "#0d9488"
+    end
+
+    def total
+      columns.values.sum(&:size)
+    end
+  end
+end

data/lib/heedkit/version.rb

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

data/lib/heedkit.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "heedkit/version"
+require "heedkit/roadmap"
+require "heedkit/changelog"
+require "heedkit/client"
+
+# Ruby / Rails SDK for HeedKit — fetch a project's public roadmap and drive the
+# end-user feedback API (identify / list / submit / vote / comment) from your server.
+#
+#   HeedKit.configure do |c|
+#     c.project_key = "fk_..."
+#     c.endpoint    = "https://acme.heedkit.com"   # your HeedKit base URL
+#   end
+#
+#   HeedKit.roadmap            # => HeedKit::Roadmap
+#   HeedKit.client.identify(external_id: "u-1")
+module HeedKit
+  class Error < StandardError; end
+
+  class Configuration
+    attr_accessor :project_key, :endpoint, :timeout
+
+    def initialize
+      @endpoint = "https://api.heedkit.com"
+      @timeout = 5
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # A client built from the global configuration.
+    def client
+      Client.new(project_key: configuration.project_key, endpoint: configuration.endpoint, timeout: configuration.timeout)
+    end
+
+    def roadmap
+      client.roadmap
+    end
+
+    def changelog
+      client.changelog
+    end
+  end
+end
+
+require "heedkit/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: heedkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- HeedKit
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Fetch a project's public roadmap and drive the end-user feedback API
+  (identify / list / submit / vote / comment) from your Ruby or Rails server.
+email:
+- support@heedkit.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/heedkit.rb
+- lib/heedkit/changelog.rb
+- lib/heedkit/client.rb
+- lib/heedkit/railtie.rb
+- lib/heedkit/roadmap.rb
+- lib/heedkit/version.rb
+homepage: https://heedkit.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://heedkit.com
+  source_code_uri: https://github.com/heedkit/heedkit-sdk-ruby
+  bug_tracker_uri: https://github.com/heedkit/heedkit-sdk-ruby/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby / Rails SDK for HeedKit — public roadmap + feedback API
+test_files: []