heedkit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d90db8da72e11a9058298022e35575c16bb5ddc99ed82e99f311cd337b017f36
-  data.tar.gz: c6bb8675fad6cba884df875a86617ad9fb2df24a822662fbf58ce20cc94632b4
+  metadata.gz: 4698932cd6e8ecddfd61917c6003c55149e36cb04727182776a692714cab1e1a
+  data.tar.gz: 3cfe868e7d6073346735bc69977bb73dce742a66015d3d818d9a91fbd177c79e
 SHA512:
-  metadata.gz: 548f044f2276926ebe16960f0da8969dab328e9546edb392e6344dc208fbd56458034f0284585349b78a9b09a3d56ea2169a166bb35bdadd46081d808258ad8c
-  data.tar.gz: 4429b95f990e9065fc41569cc8b2fd59dcaf5d0bedb2d4533ddf401c2086d1103741b63b7f0c163c48f8a1577431229b12d03d6e3298ba8146bd14cb69e9f45f
+  metadata.gz: 2f60562b31b82e6b6e572b1515ce0a26c6b7f2c6a000b889ec7d1a3785b581f8908d7cb028d766959fef0fd339a297c156d3f6578cec802c927a792a30b3ce1d
+  data.tar.gz: 3f1a9e51e15843bde1c925077e0293a78919c81e4766a598bd11bb4dc939fb362afc5a56a2fa7a3c65d9d4418814d92ad35f87c9d94b0ef2224a4b57effde41a

data/README.md

@@ -14,6 +14,7 @@ gem "heedkit"
 HeedKit.configure do |c|
   c.project_key = ENV["HEEDKIT_PROJECT_KEY"]   # "fk_..."
   c.endpoint    = "https://acme.heedkit.com"   # your HeedKit base URL
+  c.secret_key  = ENV["HEEDKIT_SERVER_SECRET"] # "fk_secret_..." — lets identify() sign users
 end
 ```
 
@@ -41,11 +42,30 @@ and views:
 
 ```ruby
 fk = HeedKit.client
+# With secret_key configured, identify() signs the external_id automatically
+# (the API rejects unsigned ids with 401 invalid_user_signature).
 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")
+identity = user["identity"] # signed replay token — pass it to the calls below
+
+fk.submit(identity:, title: "Dark mode", kind: "feature_request")
+fk.features(identity:, sort: "top")      # identity optional here (anonymous list works)
+fk.vote(feature_id, identity:)
+fk.comment(feature_id, identity:, body: "Yes please")
+```
+
+The client is stateless — one instance can serve many end-users; each call carries the
+`identity` token of the user it acts for (`X-HeedKit-Identity` header).
+
+Serving a browser widget? Expose the signed payload from an authenticated route and pass
+it to the JS SDK:
+
+```ruby
+# GET /heedkit/identity (authenticated)
+render json: {
+  externalId: current_user.id.to_s,
+  userHash: HeedKit.client.user_hash_for(current_user.id),
+  name: current_user.name, email: current_user.email
+}
 ```
 
 `identify` / `submit` / `features` / `vote` / `comment` authenticate with the project key

data/lib/heedkit/client.rb

@@ -3,24 +3,42 @@
 require "net/http"
 require "json"
 require "uri"
+require "openssl"
 
 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).
+  #
+  # Identity: this SDK runs where the project SECRET may live, so it can sign
+  # identities itself — configure `secret_key` and #identify computes the required
+  # user_hash automatically (or expose #user_hash_for to your frontend widget).
+  # Authenticated calls (submit/vote/comment) take the `identity` token #identify
+  # returned; the client is stateless so one instance can serve many end-users.
   class Client
     DEFAULT_TIMEOUT = 5
 
     attr_reader :project_key, :endpoint
 
-    def initialize(project_key:, endpoint:, timeout: DEFAULT_TIMEOUT)
+    def initialize(project_key:, endpoint:, secret_key: nil, 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("/")
+      @secret_key = secret_key
       @timeout = timeout
     end
 
+    # HMAC_SHA256(secret_key, external_id) as lowercase hex — the signature /sdk/init
+    # requires alongside any external_id (unsigned ids are rejected with
+    # 401 invalid_user_signature). Also handy for building the identity payload a
+    # frontend widget fetches ({ externalId, userHash, name, email }).
+    def user_hash_for(external_id)
+      raise Error, "secret_key not configured — pass secret_key: to HeedKit::Client.new" if @secret_key.to_s.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", @secret_key, external_id.to_s)
+    end
+
     # GET the public roadmap. Returns a HeedKit::Roadmap.
     def roadmap
       Roadmap.from_payload(get("/public/projects/#{project_key}/roadmap"))
@@ -32,44 +50,52 @@ module HeedKit
     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_user_id" => ..., "identity" => "<replay token>", "project" => {...} });
+    # pass that "identity" to submit/vote/comment. With an external_id, user_hash is
+    # computed from the configured secret_key when not given explicitly.
+    def identify(external_id: nil, user_hash: nil, email: nil, name: nil, avatar_url: nil, platform: nil)
+      user_hash ||= user_hash_for(external_id) if external_id && !@secret_key.to_s.empty?
+      sdk_post("/sdk/init", external_id:, user_hash:, 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)
+    # GET /sdk/features — public features, plus the caller's own private submissions
+    # when an identity token is given.
+    def features(identity: nil, status: nil, kind: nil, sort: "top", cursor: nil)
+      query = { status:, kind:, sort:, cursor: }.compact
+      sdk_get("/sdk/features", query, identity:)
     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:)
+    # POST /sdk/features — submit a feature as the end-user the token names.
+    def submit(identity:, title:, description: nil, kind: "feature_request", tag: nil)
+      sdk_post("/sdk/features", identity:, 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:)
+    # POST /sdk/features/:id/vote — toggle the end-user's vote.
+    def vote(feature_id, identity:)
+      sdk_post("/sdk/features/#{feature_id}/vote", identity:)
     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:)
+    # POST /sdk/features/:id/comments — comment as the end-user the token names.
+    def comment(feature_id, identity:, body:)
+      sdk_post("/sdk/features/#{feature_id}/comments", identity:, body:)
     end
 
     private
 
-    def sdk_get(path, query)
-      get(path, query:, headers: key_header)
+    def sdk_get(path, query, identity: nil)
+      get(path, query:, headers: key_header(identity))
     end
 
-    def sdk_post(path, **body)
-      post(path, body: body.compact, headers: key_header)
+    def sdk_post(path, identity: nil, **body)
+      post(path, body: body.compact, headers: key_header(identity))
     end
 
-    def key_header
-      { "X-Project-Key" => project_key }
+    # Project key + (when present) the signed identity replay token. The caller is
+    # identified by this header, never by body params.
+    def key_header(identity = nil)
+      h = { "X-Project-Key" => project_key }
+      h["X-HeedKit-Identity"] = identity if identity
+      h
     end
 
     def get(path, query: {}, headers: {})

data/lib/heedkit/version.rb

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

data/lib/heedkit.rb

@@ -19,7 +19,10 @@ module HeedKit
   class Error < StandardError; end
 
   class Configuration
-    attr_accessor :project_key, :endpoint, :timeout
+    # secret_key is the project's SERVER secret (fk_secret_…) — set it so
+    # Client#identify can sign external ids (user_hash). Keep it out of anything
+    # that reaches a browser or app binary.
+    attr_accessor :project_key, :endpoint, :secret_key, :timeout
 
     def initialize
       @endpoint = "https://api.heedkit.com"
@@ -38,7 +41,8 @@ module HeedKit
 
     # A client built from the global configuration.
     def client
-      Client.new(project_key: configuration.project_key, endpoint: configuration.endpoint, timeout: configuration.timeout)
+      Client.new(project_key: configuration.project_key, endpoint: configuration.endpoint,
+                 secret_key: configuration.secret_key, timeout: configuration.timeout)
     end
 
     def roadmap

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: heedkit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - HeedKit