deskcrew-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 948e98697c70fa23d2d3867beac3ef8b9b818ff6945f613529201d9493e68605
+  data.tar.gz: 8598b9154df830408ff02afdaeac34993aa7cee6433261620efae04245a2a376
+SHA512:
+  metadata.gz: b7c3a60b6d1a2be32b59bde4f114904805fc8bde9cff2492d84f50409cff7b7b9ac995fa929a487e1044e9acc604e0e9bb6ae96ee1ade61233151b6a481bfcee
+  data.tar.gz: 41b3b24b5bc2166e8375c9c51dab28037cac571b1049fe6cb1105c0eb4c1379deff7c3210c3bf4ee8de9b351796252d8856a452c6dc9e4cfc863b9b20713c518

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- First release: `deskcrew_widget_tag` view helper, opt-in `Deskcrew::Middleware` that injects the widget before `</body>`, `Deskcrew::Client` for `register_origin` and `create_ticket`, `rails g deskcrew:install`, and the `deskcrew:register_origin` rake task.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeskCrew
+
+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,82 @@
+# deskcrew-rails
+
+![DeskCrew widget on every Rails page](https://deskcrew.io/packages/deskcrew-rails.gif)
+
+Add the [DeskCrew](https://deskcrew.io) AI support widget to a Ruby on Rails app, and create support tickets from your own code. DeskCrew is an AI-powered helpdesk: the widget answers visitors from your knowledge base, anything it cannot answer becomes a ticket, and you approve every reply before it sends.
+
+You need a free DeskCrew account to get a widget key: https://deskcrew.io/signup
+
+## Install
+
+```ruby
+# Gemfile
+gem "deskcrew-rails"
+```
+
+```bash
+bundle install
+bin/rails generate deskcrew:install
+```
+
+The generator writes `config/initializers/deskcrew.rb`:
+
+```ruby
+Deskcrew.configure do |config|
+  config.widget_key = ENV.fetch("DESKCREW_WIDGET_KEY", nil) # "pub_..." from your dashboard's Install page
+  config.board = ENV.fetch("DESKCREW_BOARD", nil)           # your board slug
+  config.site_url = "https://www.example.com"               # this site's public origin
+  # config.color = "#4f46e5"
+  # config.position = "right"                               # or "left"
+  # config.greeting = "Hi! How can we help?"
+  # config.auto_inject = true                               # see below
+  # config.enabled = !Rails.env.test?
+end
+```
+
+## Show the widget
+
+Either add the helper to your layout, just before `</body>`:
+
+```erb
+<%= deskcrew_widget_tag %>
+```
+
+or set `config.auto_inject = true` and a middleware adds the same tag to every successful HTML response. JSON, redirects, streams and error pages are left alone, and a page that already carries the tag is never given a second one.
+
+## Allow your domain
+
+The widget only runs on origins you have registered. Once per environment:
+
+```bash
+bin/rails deskcrew:register_origin
+```
+
+This sends your `site_url` to DeskCrew together with your public widget key. The same thing happens when you paste the key on the dashboard's Install page, so run it only if you configured the key here first.
+
+## Create tickets from your code
+
+```ruby
+Deskcrew::Client.create_ticket(
+  name: current_user.name,
+  email: current_user.email,
+  message: params[:message]
+)
+```
+
+Returns `true` when DeskCrew accepted the ticket, `false` otherwise. It never raises into your request cycle, and the call takes at most ten seconds, so wrap it in a background job if you create tickets in bulk.
+
+## What the gem sends to DeskCrew
+
+- The widget script tag points at `https://deskcrew.io/desk.js` with your public widget key and the optional board, colour, position and greeting. Every value is validated and HTML-escaped before it reaches the page.
+- `deskcrew:register_origin` posts your `site_url` and widget key to `https://deskcrew.io/api/widget/register-origin`.
+- `Deskcrew::Client.create_ticket` posts the name, email and message to `https://deskcrew.io/api/widget/submit` with your `site_url` as the Origin.
+
+Nothing else leaves your app. Terms: https://deskcrew.io/terms. Privacy: https://deskcrew.io/privacy.
+
+## Requirements
+
+Ruby 3.0 or newer, Rails 6.1 or newer.
+
+## License
+
+MIT. See LICENSE.txt.

data/lib/deskcrew/client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Deskcrew
+  # Two calls, both plain HTTPS to DeskCrew:
+  #   Deskcrew::Client.register_origin   -> lets the widget run on config.site_url
+  #   Deskcrew::Client.create_ticket(...) -> a support ticket from your own code
+  # Both are best-effort: a network failure returns false, never raises into your app.
+  class Client
+    TIMEOUT = 10
+
+    class << self
+      def register_origin(config = Deskcrew.config, http: nil)
+        return false unless config.widget_ready? && config.site_url.to_s.start_with?("https://")
+
+        post(config, "/api/widget/register-origin", { key: config.widget_key, origin: config.site_url }, http: http)
+      end
+
+      def create_ticket(name: nil, email:, message:, config: Deskcrew.config, http: nil)
+        return false unless config.widget_ready?
+        return false if email.to_s.strip.empty? || message.to_s.strip.empty?
+
+        post(
+          config,
+          "/api/widget/submit",
+          { key: config.widget_key, name: name.to_s, email: email.to_s, message: message.to_s },
+          origin: config.site_url,
+          http: http
+        )
+      end
+
+      private
+
+      def post(config, path, payload, origin: nil, http: nil)
+        uri = URI.join(config.app_url, path)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Origin"] = origin if origin
+        request.body = JSON.generate(payload)
+
+        client = http || Net::HTTP.new(uri.host, uri.port).tap do |c|
+          c.use_ssl = uri.scheme == "https"
+          c.open_timeout = TIMEOUT
+          c.read_timeout = TIMEOUT
+        end
+        response = client.request(request)
+        response.code.to_i.between?(200, 299)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/deskcrew/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Deskcrew
+  # Everything the widget and the client need. Set it once in
+  # config/initializers/deskcrew.rb (rails g deskcrew:install writes one).
+  class Configuration
+    # Public widget key from your DeskCrew dashboard (Install page). Starts with "pub_".
+    attr_accessor :widget_key
+    # Your board slug, e.g. "acme" for deskcrew.io/board/acme.
+    attr_accessor :board
+    # Widget accent colour as a hex string, e.g. "#4f46e5".
+    attr_accessor :color
+    # "right" (default) or "left".
+    attr_accessor :position
+    # First line the widget shows, up to 120 characters.
+    attr_accessor :greeting
+    # Your site's public origin, e.g. "https://www.example.com". Used to register the
+    # widget for your domain and as the Origin of tickets created by the client.
+    attr_accessor :site_url
+    # Set false to keep the widget off without removing the gem.
+    attr_accessor :enabled
+    # When true, a middleware injects the widget before </body> on HTML responses.
+    # Leave false and call deskcrew_widget_tag in your layout instead.
+    attr_accessor :auto_inject
+    # Where DeskCrew lives. Only change this if DeskCrew tells you to.
+    attr_accessor :app_url
+
+    KEY_FORMAT = /\Apub_[A-Za-z0-9]+\z/
+    BOARD_FORMAT = /\A[a-z0-9-]+\z/
+    COLOR_FORMAT = /\A#[0-9a-fA-F]{6}\z/
+    GREETING_MAX = 120
+
+    def initialize
+      @widget_key = ENV.fetch("DESKCREW_WIDGET_KEY", nil)
+      @board = ENV.fetch("DESKCREW_BOARD", nil)
+      @color = nil
+      @position = "right"
+      @greeting = nil
+      @site_url = nil
+      @enabled = true
+      @auto_inject = false
+      @app_url = "https://deskcrew.io"
+    end
+
+    # True when there is a usable key and the widget is switched on.
+    def widget_ready?
+      enabled && KEY_FORMAT.match?(widget_key.to_s)
+    end
+
+    # Values the way the widget accepts them; bad input is dropped, never passed through.
+    def sanitized
+      {
+        key: (KEY_FORMAT.match?(widget_key.to_s) ? widget_key : nil),
+        board: (BOARD_FORMAT.match?(board.to_s) ? board : nil),
+        color: (COLOR_FORMAT.match?(color.to_s) ? color : nil),
+        position: (%w[left right].include?(position.to_s) ? position.to_s : nil),
+        greeting: (greeting.to_s.empty? ? nil : greeting.to_s[0, GREETING_MAX])
+      }
+    end
+  end
+end

data/lib/deskcrew/helper.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Deskcrew
+  # View helper. In your layout, just before </body>:
+  #   <%= deskcrew_widget_tag %>
+  module Helper
+    def deskcrew_widget_tag
+      html = Deskcrew::Widget.tag
+      html.respond_to?(:html_safe) ? html.html_safe : html # rubocop:disable Rails/OutputSafety
+    end
+  end
+end

data/lib/deskcrew/middleware.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Deskcrew
+  # Opt-in (config.auto_inject = true): adds the widget tag before </body> on successful
+  # HTML responses. Skips responses that already carry the tag, non-HTML bodies, and
+  # anything that is not a 200, so JSON, redirects, streams and errors are untouched.
+  class Middleware
+    MARKER = "desk.js"
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      return [status, headers, body] unless inject?(status, headers)
+
+      tag = Deskcrew::Widget.tag
+      return [status, headers, body] if tag.empty?
+
+      html = +""
+      body.each { |part| html << part.to_s }
+      body.close if body.respond_to?(:close)
+      return [status, headers, [html]] if html.include?(MARKER)
+
+      injected = html.sub(%r{</body>}i) { "#{tag}\n</body>" }
+      set_length(headers, injected)
+      [status, headers, [injected]]
+    end
+
+    private
+
+    def inject?(status, headers)
+      return false unless status.to_i == 200
+      return false unless Deskcrew.config.widget_ready?
+
+      type = header(headers, "Content-Type").to_s
+      type.include?("text/html")
+    end
+
+    def header(headers, name)
+      headers[name] || headers[name.downcase]
+    end
+
+    def set_length(headers, html)
+      key = headers.key?("content-length") ? "content-length" : "Content-Length"
+      headers[key] = html.bytesize.to_s if headers.key?("Content-Length") || headers.key?("content-length")
+    end
+  end
+end

data/lib/deskcrew/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Deskcrew
+  class Railtie < Rails::Railtie
+    initializer "deskcrew.helper" do
+      ActiveSupport.on_load(:action_view) { include Deskcrew::Helper }
+    end
+
+    initializer "deskcrew.middleware" do |app|
+      app.middleware.use Deskcrew::Middleware if Deskcrew.config.auto_inject
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/deskcrew.rake", __dir__)
+    end
+  end
+end

data/lib/deskcrew/version.rb

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

data/lib/deskcrew/widget.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Deskcrew
+  # Builds the one script tag the widget needs. Every attribute value is HTML-escaped
+  # and only known-good values make it into the tag (see Configuration#sanitized).
+  module Widget
+    module_function
+
+    def tag(config = Deskcrew.config)
+      return "" unless config.widget_ready?
+
+      values = config.sanitized
+      attrs = { "src" => "#{config.app_url}/desk.js", "data-key" => values[:key] }
+      attrs["data-board"] = values[:board] if values[:board]
+      attrs["data-color"] = values[:color] if values[:color]
+      attrs["data-position"] = values[:position] if values[:position]
+      attrs["data-greeting"] = values[:greeting] if values[:greeting]
+
+      pairs = attrs.map { |k, v| %(#{k}="#{ERB::Util.html_escape(v)}") }
+      "<script #{pairs.join(' ')} defer></script>"
+    end
+  end
+end

data/lib/deskcrew.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "deskcrew/version"
+require "deskcrew/configuration"
+require "deskcrew/widget"
+require "deskcrew/helper"
+require "deskcrew/middleware"
+require "deskcrew/client"
+require "deskcrew/railtie" if defined?(Rails::Railtie)
+
+module Deskcrew
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def reset!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/generators/deskcrew/install/install_generator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Deskcrew
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Writes config/initializers/deskcrew.rb"
+
+      def create_initializer
+        template "deskcrew.rb.tt", "config/initializers/deskcrew.rb"
+      end
+
+      def show_next_steps
+        say ""
+        say "DeskCrew installed. Next:", :green
+        say "  1. Put your widget key in config/initializers/deskcrew.rb (or DESKCREW_WIDGET_KEY)."
+        say "  2. Add <%= deskcrew_widget_tag %> before </body> in your layout, or set auto_inject = true."
+        say "  3. Run bin/rails deskcrew:register_origin once per environment."
+      end
+    end
+  end
+end

data/lib/generators/deskcrew/install/templates/deskcrew.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# DeskCrew support widget. Get the key from your DeskCrew dashboard, Install page.
+Deskcrew.configure do |config|
+  config.widget_key = ENV.fetch("DESKCREW_WIDGET_KEY", nil) # "pub_..."
+  config.board = ENV.fetch("DESKCREW_BOARD", nil)           # your board slug
+  config.site_url = "https://www.example.com"               # this site's public origin
+  # config.color = "#4f46e5"
+  # config.position = "right"
+  # config.greeting = "Hi! How can we help?"
+  # config.auto_inject = true   # or call deskcrew_widget_tag in your layout
+  # config.enabled = !Rails.env.test?
+end

data/lib/tasks/deskcrew.rake

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+namespace :deskcrew do
+  desc "Register this site's origin with DeskCrew so the widget is allowed on your domain"
+  task register_origin: :environment do
+    config = Deskcrew.config
+    abort "DeskCrew: set config.widget_key and config.site_url (https://...) first" unless config.widget_ready? && config.site_url.to_s.start_with?("https://")
+    if Deskcrew::Client.register_origin
+      puts "DeskCrew: #{config.site_url} registered for widget key #{config.widget_key[0, 8]}…"
+    else
+      abort "DeskCrew: registration failed; check the key on your dashboard's Install page"
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: deskcrew-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- DeskCrew
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description: DeskCrew is an AI-powered helpdesk. This gem injects the DeskCrew support
+  widget into your Rails views (a helper or an opt-in middleware), registers your
+  site with DeskCrew so the widget works on your domain, and gives you a small client
+  to create support tickets from your own code.
+email:
+- support@deskcrew.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/deskcrew.rb
+- lib/deskcrew/client.rb
+- lib/deskcrew/configuration.rb
+- lib/deskcrew/helper.rb
+- lib/deskcrew/middleware.rb
+- lib/deskcrew/railtie.rb
+- lib/deskcrew/version.rb
+- lib/deskcrew/widget.rb
+- lib/generators/deskcrew/install/install_generator.rb
+- lib/generators/deskcrew/install/templates/deskcrew.rb.tt
+- lib/tasks/deskcrew.rake
+homepage: https://deskcrew.io/integrations/rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://deskcrew.io/integrations/rails
+  documentation_uri: https://deskcrew.io/board/deskcrew/kb
+  source_code_uri: https://github.com/webmilmind1/support-tickets/tree/main/rails-gem
+  changelog_uri: https://github.com/webmilmind1/support-tickets/blob/main/rails-gem/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.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Add the DeskCrew AI support widget to a Rails app and turn form submissions
+  into tickets.
+test_files: []