kavchat 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa8a26f7733da2ec296d48c70dacd3fdbb5322bb947392ea2403001b980115c9
+  data.tar.gz: d50e780566c163f226fbab6c8bf32741fcaec72e05ca4d88c47b512cfd0b527f
+SHA512:
+  metadata.gz: a1112f8f47542bd4d134c1ab614441d71e8482c5c57d5fec83fe55c30d2fb9fed6622a5c30b9ce6990748a29f3357a7873ded02498678ae058f8b0bf40f38803
+  data.tar.gz: d8cd1864977262b1dec77ab6276ce565af0bdd09e390873aa7aff2afbc0b539a21483ec408ad3c33f876a3390bf7e281ada63371c99566e222516c28e16c2f07

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+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,79 @@
+# kavchat (Ruby)
+
+Kavchat server SDK for Ruby 2.6+. Standard library only (`net/http`, `openssl`, `json`).
+
+## Install
+
+```ruby
+gem "kavchat"
+```
+
+## Setup
+
+```ruby
+require "kavchat"
+
+kavchat = Kavchat::Client.new(
+  ENV.fetch("KAVCHAT_SECRET_KEY"),
+  # base_url: "https://api.kavchat.com",
+  # timeout: 30,
+  # locale: "en"
+)
+```
+
+## Identify your users
+
+```ruby
+token = kavchat.create_user_token(
+  user_id: "user_123",        # required, 1 to 128 characters
+  phone: "+972501234567",
+  name: "Dana",
+  email: "dana@example.com",
+  expires_in: 7 * 24 * 3600   # seconds, default 7 days, at most 30 days
+)
+```
+
+`Kavchat.create_user_token(secret_key, user_id: ...)` is the module level version.
+
+## Verify webhooks (Rails)
+
+```ruby
+class KavchatWebhooksController < ActionController::API
+  def create
+    event = KAVCHAT.verify_webhook(request.raw_post, request.headers["Kavchat-Signature"])
+    Rails.logger.info("New ticket #{event.data.number}") if event.type == "ticket.created"
+    head :ok
+  rescue Kavchat::WebhookVerificationError => e
+    render plain: e.code, status: :bad_request
+  end
+end
+```
+
+`Client#verify_webhook` returns a `Kavchat::WebhookEvent`. `Kavchat.verify_webhook` returns the plain Hash.
+
+## Server API
+
+Responses are read-only models with snake_case readers (`ticket.topic_name`). `#[]` and `#to_h` give the raw hash.
+
+```ruby
+kavchat.get_workspace
+kavchat.list_tickets(status: "open", limit: 50, before: 120)
+kavchat.get_ticket(id)
+kavchat.set_ticket_status(id, "closed")
+kavchat.get_reports(from: Time.now - 7 * 86_400, to: Time.now)
+kavchat.get_settings
+kavchat.update_settings(audience: "testers", tester_phones: ["+972501234567"])
+kavchat.list_releases
+```
+
+Errors raise `Kavchat::ApiError` with `status`, `code`, `message` and `details`. `status` is 0 for `timeout` and `network_error`.
+
+## Tests
+
+```sh
+rake test
+```
+
+## License and support
+
+MIT. Documentation: https://kavchat.com/docs/. Questions: support@kavchat.com.

data/lib/kavchat/client.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+module Kavchat
+  DEFAULT_BASE_URL = "https://api.kavchat.com"
+
+  # Kavchat Server API client. Keep the secret key on your backend only.
+  #
+  #   kavchat = Kavchat::Client.new(ENV.fetch("KAVCHAT_SECRET_KEY"))
+  class Client
+    attr_reader :base_url, :timeout, :locale
+
+    def initialize(secret_key, base_url: DEFAULT_BASE_URL, timeout: 30, locale: nil)
+      raise ArgumentError, "secret_key is required" if !secret_key.is_a?(String) || secret_key.empty?
+
+      @secret_key = secret_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @locale = locale
+    end
+
+    def inspect
+      "#<Kavchat::Client base_url=#{@base_url.inspect}>"
+    end
+
+    # Signs an identity token for one of your users. See Kavchat.create_user_token.
+    def create_user_token(**options)
+      Kavchat.create_user_token(@secret_key, **options)
+    end
+
+    # Verifies a webhook request and returns a Kavchat::WebhookEvent. See Kavchat.verify_webhook.
+    def verify_webhook(raw_body, signature_header, tolerance_seconds = DEFAULT_TOLERANCE_SECONDS, now: nil)
+      WebhookEvent.new(Kavchat.verify_webhook(@secret_key, raw_body, signature_header, tolerance_seconds, now: now))
+    end
+
+    def get_workspace
+      Workspace.new(request(:get, "/workspace"))
+    end
+
+    # Newest first. Page with before: the number of the last ticket you have.
+    def list_tickets(status: nil, limit: nil, before: nil)
+      request(:get, "/tickets", query: { status: status, limit: limit, before: before }).map { |t| Ticket.new(t) }
+    end
+
+    def get_ticket(id)
+      Ticket.new(request(:get, "/tickets/#{escape(id)}"))
+    end
+
+    # status: "open" or "closed"
+    def set_ticket_status(id, status)
+      Ticket.new(request(:put, "/tickets/#{escape(id)}/status", body: { status: status.to_s }))
+    end
+
+    # Defaults to the last 30 days. from/to accept Time or an ISO 8601 string.
+    def get_reports(from: nil, to: nil)
+      Report.new(request(:get, "/reports", query: { from: iso(from), to: iso(to) }))
+    end
+
+    def get_settings
+      Settings.new(request(:get, "/settings"))
+    end
+
+    # Only the audience and the tester phones can be changed from the server.
+    def update_settings(audience: nil, tester_phones: nil)
+      body = {}
+      body[:audience] = audience.to_s unless audience.nil?
+      body[:testerPhones] = Array(tester_phones) unless tester_phones.nil?
+      Settings.new(request(:put, "/settings", body: body))
+    end
+
+    def list_releases
+      request(:get, "/releases").map { |r| ReleaseSummary.new(r) }
+    end
+
+    private
+
+    def escape(id)
+      URI.encode_www_form_component(id.to_s).gsub("+", "%20")
+    end
+
+    def iso(value)
+      value.respond_to?(:utc) ? value.utc.iso8601(3) : value
+    end
+
+    def request(method, path, query: nil, body: nil)
+      uri = URI("#{@base_url}/v1/server#{path}")
+      params = (query || {}).reject { |_, v| v.nil? || v == "" }
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      req = (method == :put ? Net::HTTP::Put : Net::HTTP::Get).new(uri)
+      req["Authorization"] = "Bearer #{@secret_key}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "kavchat-ruby/#{VERSION}"
+      req["Accept-Language"] = @locale if @locale
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      res = begin
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: @timeout, read_timeout: @timeout, write_timeout: @timeout) do |http|
+          http.request(req)
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+        raise ApiError.new(0, "timeout", "Request timed out after #{@timeout} s")
+      rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+        raise ApiError.new(0, "network_error", "Could not reach Kavchat: #{e.message}")
+      end
+
+      status = res.code.to_i
+      payload = begin
+        res.body.nil? || res.body.empty? ? nil : JSON.parse(res.body.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError
+        nil
+      end
+      if !payload.is_a?(Hash) || !(200..299).cover?(status) || payload["success"] != true
+        if payload.is_a?(Hash) && payload["code"].is_a?(String)
+          raise ApiError.new(status, payload["code"], (payload["message"] || payload["code"]).to_s, payload["details"])
+        end
+
+        raise ApiError.new(status, "invalid_response", "Unexpected response from Kavchat (HTTP #{status})")
+      end
+      payload["data"]
+    end
+  end
+end

data/lib/kavchat/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kavchat
+  # Base class of every error raised by this SDK.
+  class Error < StandardError; end
+
+  # The Server API answered with an error, or could not be reached.
+  # +status+ is the HTTP status, or 0 when no response arrived
+  # (+code+ is then "timeout" or "network_error").
+  class ApiError < Error
+    attr_reader :status, :code, :details
+
+    def initialize(status, code, message, details = nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+    end
+  end
+
+  # A webhook request failed verification. Answer it with HTTP 400.
+  # +code+ is malformed_header, timestamp_out_of_range, invalid_signature or invalid_payload.
+  class WebhookVerificationError < Error
+    attr_reader :code
+
+    def initialize(code, message)
+      super(message)
+      @code = code
+    end
+  end
+end

data/lib/kavchat/identity.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Kavchat
+  DEFAULT_TOKEN_TTL_SECONDS = 7 * 24 * 60 * 60
+  MAX_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60
+
+  # base64url of {"alg":"HS256","typ":"JWT"}
+  JWT_HEADER = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
+  private_constant :JWT_HEADER
+
+  module_function
+
+  # Signs an identity token (HS256 JWT) for one of your users.
+  # +expires_in+ is in seconds (default 7 days, at most 30 days).
+  # +issued_at+ is unix seconds and defaults to now.
+  def create_user_token(secret_key, user_id:, phone: nil, name: nil, email: nil,
+                        expires_in: DEFAULT_TOKEN_TTL_SECONDS, issued_at: nil)
+    raise ArgumentError, "secret_key is required" if !secret_key.is_a?(String) || secret_key.empty?
+    unless user_id.is_a?(String) && (1..128).cover?(user_id.encode("UTF-16LE").bytesize / 2)
+      raise ArgumentError, "user_id must be a string of 1 to 128 characters"
+    end
+    unless expires_in.is_a?(Integer) && expires_in.positive? && expires_in <= MAX_TOKEN_TTL_SECONDS
+      raise ArgumentError, "expires_in must be a whole number of seconds between 1 and #{MAX_TOKEN_TTL_SECONDS}"
+    end
+
+    iat = (issued_at || Time.now).to_i
+    # Claim order is fixed (sub, phone, name, email, iat, exp) so every SDK signs the same bytes.
+    claims = { "sub" => user_id }
+    claims["phone"] = phone if phone && !phone.empty?
+    claims["name"] = name if name && !name.empty?
+    claims["email"] = email if email && !email.empty?
+    claims["iat"] = iat
+    claims["exp"] = iat + expires_in
+
+    payload = b64url(JSON.generate(claims))
+    signature = b64url(OpenSSL::HMAC.digest("SHA256", secret_key, "#{JWT_HEADER}.#{payload}"))
+    "#{JWT_HEADER}.#{payload}.#{signature}"
+  end
+
+  def b64url(data)
+    Base64.urlsafe_encode64(data, padding: false)
+  end
+  private_class_method :b64url
+end

data/lib/kavchat/models.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Kavchat
+  # Read-only view over a JSON object from the API. Fields are exposed as snake_case
+  # readers (ticket.topic_name); the raw hash stays available through #[] and #to_h.
+  class Model
+    def self.fields(mapping)
+      mapping.each do |name, (key, type)|
+        define_method(name) { convert(@raw[key], type) }
+      end
+    end
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    def [](key)
+      @raw[key.to_s]
+    end
+
+    def to_h
+      @raw
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_h == to_h
+    end
+
+    private
+
+    def convert(value, type)
+      return value if type.nil? || value.nil?
+      return value.map { |v| convert(v, type.first) } if type.is_a?(Array)
+
+      type.new(value)
+    end
+  end
+
+  class TranscriptEntry < Model
+    fields from: ["from"], text: ["text"], step_id: ["stepId"], at: ["at"]
+  end
+
+  class Ticket < Model
+    fields id: ["id"], number: ["number"], status: ["status"], name: ["name"], email: ["email"],
+           phone: ["phone"], user_id: ["userId"], topic_id: ["topicId"], topic_name: ["topicName"],
+           script_id: ["scriptId"], session_id: ["sessionId"], message: ["message"],
+           transcript: ["transcript", [TranscriptEntry]], created_at: ["createdAt"], updated_at: ["updatedAt"]
+  end
+
+  class ContactTopic < Model
+    fields id: ["id"], name: ["name"]
+  end
+
+  class Settings < Model
+    fields enabled: ["enabled"], audience: ["audience"], tester_phones: ["testerPhones"], bot_name: ["botName"],
+           avatar_text: ["avatarText"], avatar_image_url: ["avatarImageUrl"], subtitle: ["subtitle"],
+           primary_color: ["primaryColor"], position: ["position"], contact_topics: ["contactTopics", [ContactTopic]]
+  end
+
+  class Workspace < Model
+    fields id: ["id"], name: ["name"], locale: ["locale"], default_country: ["defaultCountry"], plan: ["plan"],
+           public_key: ["publicKey"], secret_key_hint: ["secretKeyHint"], webhook_url: ["webhookUrl"]
+  end
+
+  class ReleaseScript < Model
+    fields id: ["id"], kind: ["kind"], name: ["name"]
+  end
+
+  class ReleaseSummary < Model
+    fields version: ["version"], note: ["note"], restored_from: ["restoredFrom"], published_at: ["publishedAt"],
+           scripts: ["scripts", [ReleaseScript]]
+  end
+
+  class ReportTotals < Model
+    fields sessions: ["sessions"], open: ["open"], answered: ["answered"], contact: ["contact"], abandoned: ["abandoned"]
+  end
+
+  class UnmatchedQuestion < Model
+    fields group_key: ["groupKey"], sample: ["sample"], count: ["count"], last_at: ["lastAt"]
+  end
+
+  class Report < Model
+    fields from: ["from"], to: ["to"], totals: ["totals", ReportTotals], by_script: ["byScript"],
+           drop_off: ["dropOff"], unmatched: ["unmatched", [UnmatchedQuestion]]
+  end
+
+  class WebhookEvent < Model
+    fields type: ["type"], data: ["data", Ticket]
+  end
+end

data/lib/kavchat/version.rb

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

data/lib/kavchat/webhook.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Kavchat
+  SIGNATURE_HEADER = "Kavchat-Signature"
+  DEFAULT_TOLERANCE_SECONDS = 300
+
+  module_function
+
+  # Checks the Kavchat-Signature header and returns the parsed event (a Hash).
+  # +raw_body+ must be the exact bytes received, before any JSON parsing.
+  # Raises Kavchat::WebhookVerificationError when the request is not authentic or too old.
+  def verify_webhook(secret_key, raw_body, signature_header, tolerance_seconds = DEFAULT_TOLERANCE_SECONDS, now: nil)
+    timestamp = nil
+    bad_timestamp = false
+    signatures = []
+    signature_header.to_s.split(",").each do |part|
+      key, sep, value = part.partition("=")
+      next if sep.empty?
+
+      key = key.strip
+      value = value.strip
+      if key == "t"
+        if value.match?(/\A\d+\z/)
+          timestamp = value.to_i
+        else
+          bad_timestamp = true
+        end
+      elsif key == "v1" && !value.empty?
+        signatures << value
+      end
+    end
+    if timestamp.nil? || bad_timestamp || signatures.empty?
+      raise WebhookVerificationError.new("malformed_header", "Kavchat-Signature header is missing or malformed")
+    end
+
+    current = (now || Time.now).to_i
+    if (current - timestamp).abs > tolerance_seconds
+      raise WebhookVerificationError.new("timestamp_out_of_range", "Webhook timestamp is outside the tolerance")
+    end
+
+    body = raw_body.to_s.dup.force_encoding(Encoding::BINARY)
+    expected = OpenSSL::HMAC.hexdigest("SHA256", secret_key, "#{timestamp}.".b + body)
+    unless signatures.any? { |sig| secure_compare(expected, sig) }
+      raise WebhookVerificationError.new("invalid_signature", "Webhook signature does not match")
+    end
+
+    begin
+      JSON.parse(body.force_encoding(Encoding::UTF_8))
+    rescue JSON::ParserError, EncodingError
+      raise WebhookVerificationError.new("invalid_payload", "Webhook body is not valid JSON")
+    end
+  end
+
+  # Constant time comparison (OpenSSL.secure_compare needs Ruby 2.7+).
+  def secure_compare(a, b)
+    a = a.b
+    b = b.b
+    return false unless a.bytesize == b.bytesize
+
+    diff = 0
+    a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+    diff.zero?
+  end
+  private_class_method :secure_compare
+end

data/lib/kavchat.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Kavchat server SDK: identity tokens, webhook verification and the Server API.
+require_relative "kavchat/version"
+require_relative "kavchat/errors"
+require_relative "kavchat/identity"
+require_relative "kavchat/webhook"
+require_relative "kavchat/models"
+require_relative "kavchat/client"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: kavchat
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+platform: ruby
+authors:
+- maxsave
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12'
+description: Sign identity tokens for the Kavchat widget and apps, verify ticket webhooks,
+  and call the Kavchat Server API. No runtime dependencies.
+email:
+- support@kavchat.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kavchat.rb
+- lib/kavchat/client.rb
+- lib/kavchat/errors.rb
+- lib/kavchat/identity.rb
+- lib/kavchat/models.rb
+- lib/kavchat/version.rb
+- lib/kavchat/webhook.rb
+homepage: https://kavchat.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://kavchat.com
+  documentation_uri: https://kavchat.com/docs/
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: 'Kavchat server SDK: identity tokens, webhook verification and the Server
+  API'
+test_files: []