deacon-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9b67729a41edf00bed6786b7b452d46280d312c38add74d0a8dba996c9110b2
+  data.tar.gz: 2424fcf30dc687f72f2438a837db3b90560eda33c6f8a89a22ace6c756a4e682
+SHA512:
+  metadata.gz: d58bd949062b18345c26f8a706486d5deea5e9d5e956b36861113f9c8525fc5e9326bbb4199affd8a4b8ba0b4b61b03e87184648ae5db5f78b45fb799d0f1ed4
+  data.tar.gz: 992cd18343847745069d576eefc7443854c6d8117edfc568fd1a5a3fa08fa3632200d6626fd313c47b8984e35219bf0ea1c2a795e8e3defe79431e72e38d1b6e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deacon
+
+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,99 @@
+# deacon-rails
+
+[Deacon](https://heydeacon.com) is an AI support agent that answers questions from your own docs and content, and says when it doesn't know. This gem adds its chat widget to every page of a Rails app.
+
+You need a Deacon account, and there's a free plan.
+
+## Install
+
+```sh
+bundle add deacon-rails
+```
+
+## Set it up
+
+Put the helper in the `<head>` of `app/views/layouts/application.html.erb`:
+
+```erb
+<head>
+  <%# ...the rest of your head %>
+  <%= javascript_importmap_tags %>
+  <%= deacon_widget_tag %>
+</head>
+```
+
+Then give it your key, in the `DEACON_KEY` environment variable:
+
+```sh
+DEACON_KEY=pk_your_widget_key
+```
+
+Or in an initializer, such as `config/initializers/deacon.rb`, which wins over `DEACON_KEY`:
+
+```ruby
+Rails.application.config.deacon.key = "pk_your_widget_key"
+```
+
+To find your key, open Install from the button at the top of the Deacon dashboard. The snippet there has it in `data-key`, and it starts with `pk_`. It isn't a secret: every visitor's browser reads it. If the key is missing, the helper prints nothing and logs a warning that says why, so your pages still render. An option of the wrong type raises an `ArgumentError` that says why.
+
+Deacon only runs on the sites listed on Install. A listed domain covers its subdomains, so `example.com` covers `app.example.com`. If your app lives somewhere else, such as `example.fly.dev`, add that address on Install too.
+
+When you run `bin/rails server`, Install notices the widget on `localhost:3000` and lets you add it in one click. Chats on localhost don't count towards your plan.
+
+If you tell Deacon who is signed in, with the `window.deaconUser` script from [Deacon's install guide](https://heydeacon.com/agent/install.md), put that script above `<%= deacon_widget_tag %>` in the head, because the widget reads it as it starts.
+
+## Options
+
+Set them on `config.deacon`, in an initializer or in `config/application.rb`.
+
+| Option       | Type    | Default      | What it does |
+| ------------ | ------- | ------------ | ------------ |
+| `key`        | string  | `DEACON_KEY` | Your Deacon key. |
+| `context`    | hash    | none         | Details Deacon takes into account when it answers, the same on every page, such as `{ product: "api", docs_version: "3.2" }`. Up to 12 keys, each value a string, number or boolean. Anyone can read them in the page's HTML, so never put a secret here. |
+| `page_views` | boolean | `true`       | The same script counts visits for Deacon's website analytics. Set this to `false` to send no page views or JavaScript errors from your app. Chat still works. |
+
+```ruby
+Rails.application.config.deacon.key = "pk_your_widget_key"
+Rails.application.config.deacon.context = { product: "api", docs_version: "3.2" }
+Rails.application.config.deacon.page_views = false
+```
+
+## Turbo
+
+Turbo Drive swaps the `<body>` on each visit and keeps the `<head>`, so in the head the tag runs once. Deacon puts its chat on `<html>`, outside the body, so the widget stays in place as people move between pages.
+
+## Content Security Policy
+
+If your app gives each request a nonce, with `config.content_security_policy_nonce_generator`, the tag carries it. The policy also needs Deacon's address, `https://heydeacon.com`, in `script-src`, `connect-src` and `frame-src`, and `'unsafe-inline'` in `style-src`, because the widget writes its styles where a nonce can't reach. Keep the nonce to `script-src`, since a nonce in `style-src` makes browsers ignore `'unsafe-inline'`:
+
+```ruby
+Rails.application.configure do
+  config.content_security_policy do |policy|
+    policy.script_src  :self, "https://heydeacon.com"
+    policy.style_src   :self, :unsafe_inline
+    policy.connect_src :self, "https://heydeacon.com"
+    policy.frame_src   "https://heydeacon.com"
+  end
+
+  config.content_security_policy_nonce_generator = ->(request) { request.session.id.to_s }
+  config.content_security_policy_nonce_directives = %w(script-src)
+end
+```
+
+## Opening the chat from your own button
+
+The widget comes with its own button. To use one of yours instead, hide Deacon's in Appearance in the dashboard and call `window.Deacon.open()` from your button or link. `Deacon.close()` and `Deacon.toggle()` work too.
+
+## What it adds
+
+The helper prints the same tag Install gives you:
+
+```html
+<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>
+```
+
+It loads in the background without holding up the page. Works with Rails 8.0 and later, on Ruby 3.3 and later.
+
+## License
+
+MIT

data/lib/deacon/rails/helper.rb

@@ -0,0 +1,82 @@
+require "erb"
+require "json"
+
+module Deacon
+  module Rails
+    # The view helper the layout calls once, in its head.
+    module Helper
+      LOADER_SRC = "https://heydeacon.com/widget/v1/loader.js".freeze
+
+      MISSING_KEY = "deacon-rails: the key is missing, so the page has no Deacon widget. Set " \
+                    "DEACON_KEY or config.deacon.key. In Deacon, open Install (the button at the " \
+                    "top of the dashboard) and copy the data-key value from the snippet. It " \
+                    "starts with pk_.".freeze
+
+      # The tag Install gives, with the key from config.deacon.key, or from DEACON_KEY when
+      # the app sets none. With no key it prints nothing and logs a warning, so a missing
+      # setting never takes a page down.
+      def deacon_widget_tag
+        key = (deacon_config.key || ENV["DEACON_KEY"]).to_s.strip
+
+        if key.empty?
+          ::Rails.logger&.warn(MISSING_KEY)
+          return
+        end
+
+        context = deacon_config.context
+        page_views = deacon_config.page_views
+        deacon_check_context(context)
+        deacon_check_page_views(page_views)
+
+        attributes = { "data-key" => key }
+        attributes["data-context"] = JSON.generate(context) unless context.nil?
+        attributes["data-no-page-views"] = true if page_views == false
+
+        deacon_loader_tag(attributes, deacon_csp_nonce)
+      end
+
+      private
+
+      def deacon_config
+        ::Rails.application.config.deacon
+      end
+
+      # The request's Content Security Policy nonce, when the app has a nonce generator and the
+      # page was rendered for a request.
+      def deacon_csp_nonce
+        content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+      end
+
+      # A wrong type is a mistake in the app's code, so it raises, as any view error does.
+      def deacon_check_context(context)
+        return if context.nil?
+        return if context.is_a?(Hash) && context.each_value.all? { |value| deacon_scalar?(value) }
+
+        raise ArgumentError, "deacon-rails: config.deacon.context must be a hash whose values " \
+                             "are strings, numbers or booleans."
+      end
+
+      def deacon_check_page_views(page_views)
+        return if page_views.nil? || page_views == true || page_views == false
+
+        raise ArgumentError, "deacon-rails: config.deacon.page_views must be true or false."
+      end
+
+      def deacon_scalar?(value)
+        value.is_a?(String) || value.is_a?(Integer) || value.is_a?(Float) || value == true || value == false
+      end
+
+      # The tag Install gives, with any of its other attributes between the key and async, and
+      # the nonce after them. An attribute that is true is written with no value, as async is.
+      def deacon_loader_tag(attributes, nonce)
+        rendered = attributes.map do |name, value|
+          value == true ? " #{name}" : %( #{name}="#{ERB::Util.html_escape(value)}")
+        end.join
+
+        nonce_attribute = nonce.nil? ? "" : %( nonce="#{ERB::Util.html_escape(nonce)}")
+
+        %(<script src="#{LOADER_SRC}"#{rendered} async#{nonce_attribute}></script>).html_safe
+      end
+    end
+  end
+end

data/lib/deacon/rails/railtie.rb

@@ -0,0 +1,16 @@
+module Deacon
+  module Rails
+    # What config.deacon holds. A Struct rather than ordered options, so a misspelt setting
+    # fails loudly at boot instead of being ignored.
+    Configuration = Struct.new(:key, :context, :page_views)
+
+    # Adds config.deacon to the app and deacon_widget_tag to its views.
+    class Railtie < ::Rails::Railtie
+      config.deacon = Configuration.new
+
+      initializer "deacon.view_helper" do
+        ActiveSupport.on_load(:action_view) { include Deacon::Rails::Helper }
+      end
+    end
+  end
+end

data/lib/deacon/rails/version.rb

@@ -0,0 +1,5 @@
+module Deacon
+  module Rails
+    VERSION = "1.0.0"
+  end
+end

data/lib/deacon/rails.rb

@@ -0,0 +1,3 @@
+require "deacon/rails/version"
+require "deacon/rails/helper"
+require "deacon/rails/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: deacon-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Deacon
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: A view helper, deacon_widget_tag, that puts the Deacon chat widget on
+  every page of a Rails app from one line in the layout. Deacon is an AI support agent
+  that answers questions from your own docs and content, and says when it doesn't
+  know.
+email:
+- hello@heydeacon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/deacon/rails.rb
+- lib/deacon/rails/helper.rb
+- lib/deacon/rails/railtie.rb
+- lib/deacon/rails/version.rb
+homepage: https://heydeacon.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://heydeacon.com
+  source_code_uri: https://github.com/heydeacon/deacon-rails
+  bug_tracker_uri: https://github.com/heydeacon/deacon-rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Adds Deacon, an AI support chat that answers from your docs, to every page
+  of a Rails app.
+test_files: []