rails_consent 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19e1554e153f613453261717b4d18b77bc83664efe9e35fb178553d45802ad97
-  data.tar.gz: df90bf179fe78aab0df69a290aa097c40bdedc21295d24523e6db492e53bd7be
+  metadata.gz: db41ad501b276a6a3b243164d5eb0641f5a8a4b3b0fadd3d6becfaecfbb2716c
+  data.tar.gz: 3a99070e8cb4e92b911d79cbe3b1339f81f5cbe5b62f53ead4b311b47c9e47f4
 SHA512:
-  metadata.gz: 35f2aaa9ed70c1a70e79769b0f45d03be70bddf0abf3e3ff9e5441867a6c1ddc8ef7d7c51c56dc6aa8547ddaf911a616f1083ebdb7f519e3893267f8e9cf2d1b
-  data.tar.gz: 24b811e64f10bdaaf9aab27aa48a130430caf7fb93576b99a07bb1b1a527eac8fe54b15453f1718c8ade2ab3538d437d02d568289d49d08d4b18d11ab3c8d6b8
+  metadata.gz: 7a9522f106b096c57ba280fd24a3c013f65bef654ab4fe49a72ca61e86da547a16edaf0137d629519c8906c2e901841d7695ae375f5b4baf79ab9827fc6b045a
+  data.tar.gz: 822a6f4e889cf71691a3624cdfe2d77f23609beab60df3a26a3379fd76c5b2e2d1f572cafaaef8efcc80f4c2a67a60df97b37b124a6d83d0be3704aa31cd2505

data/CHANGELOG.md

@@ -2,9 +2,13 @@
 
 ## Unreleased
 
+## 0.1.1
+
 - Relaxed the development baseline to Ruby 3.4.7 and Rails 7.1+
 - Simplified the gem contract so consent persistence stays in the host application
 - Refreshed the documentation application into a richer documentation-first Rails app with enhanced live consent demos
+- Fixed engine boot and installer helper loading so the public helper modules are available during initialization
+- Documented the supported public API and shipped RBS signatures for the stable Ruby surface
 
 ## 0.1.0
 

data/README.md

@@ -166,6 +166,89 @@ consent_recorded?
 reset_consent!
 ```
 
+## Public API
+
+Rails Consent treats the following server-side entrypoints as its supported public API for host applications:
+
+- `RailsConsent.configure`
+- `RailsConsent.configuration` and `RailsConsent.config`
+- `RailsConsent::Configuration`
+- `RailsConsent::DefaultConsentResolver`
+- `RailsConsent::CategoryLoader`
+- `RailsConsent::Category`
+- `RailsConsent::CookieDefinition`
+- `RailsConsent::PreferenceSet`
+- `RailsConsent::CookieStore` when you want to wrap the built-in signed cookie flow
+- `RailsConsent::ApplicationHelper`
+- `RailsConsent::ControllerHelpers`
+- The generated initializer and locale structure installed by `rails_consent:install`
+- The shipped partial override points under `app/views/rails_consent/*`
+- The browser API exposed through `window.RailsConsent`
+
+Everything else should be treated as internal implementation detail and may change more freely between releases.
+
+### Server-side API Reference
+
+#### Configuration
+
+```ruby
+RailsConsent.configure do |config|
+  config.storage = :cookie
+  config.banner_position = :bottom
+  config.prompt_dismissible = true
+  config.cookie_name = "rails_consent_preferences"
+  config.cookie_expiration_days = 180
+  config.consent_resolver = RailsConsent::DefaultConsentResolver.new
+end
+```
+
+`RailsConsent::Configuration` exposes these stable attributes and hooks:
+
+- `storage`
+- `banner_position`
+- `prompt_dismissible`
+- `cookie_name`
+- `cookie_expiration_days`
+- `cookie_same_site`
+- `cookie_http_only`
+- `cookie_secure`
+- `cookie_path`
+- `cookie_reader`
+- `cookie_writer`
+- `cookie_destroyer`
+- `preferences_provider`
+- `preferences_writer`
+- `preferences_destroyer`
+- `consent_recorded_provider`
+- `consent_resolver`
+- `validate!`
+
+#### Category and Preference Objects
+
+These objects are safe to use in host code when you want to inspect or extend consent behavior:
+
+```ruby
+RailsConsent::CategoryLoader.new.categories
+RailsConsent::PreferenceSet.new(categories: categories, source: raw_preferences).to_h
+RailsConsent::CookieStore.read(configuration: config, cookies: cookies, categories: categories, request: request)
+```
+
+`RailsConsent::Category` exposes:
+
+- `key`
+- `label`
+- `description`
+- `cookies`
+- `required?`
+
+`RailsConsent::CookieDefinition` exposes:
+
+- `name`
+- `provider`
+- `purpose`
+
+`RailsConsent::PreferenceSet#to_h` returns a normalized hash keyed by category name plus an optional `"timestamp"` entry.
+
 ## Client-side API
 
 Rails Consent also exposes a small browser API through `window.RailsConsent`:
@@ -188,6 +271,27 @@ Lifecycle events are dispatched on `document` so host apps can react without mod
 - `rails-consent:rejected-optional`
 - `rails-consent:dismissed`
 
+## Type Signatures
+
+Rails Consent now ships RBS signatures for its documented public API under [`sig/`](sig).
+
+That gives downstream applications and editors a machine-readable contract for the stable Ruby surface, including:
+
+- `RailsConsent.configure`
+- `RailsConsent::Configuration`
+- `RailsConsent::CategoryLoader`
+- `RailsConsent::Category`
+- `RailsConsent::PreferenceSet`
+- `RailsConsent::CookieStore`
+- `RailsConsent::ApplicationHelper`
+- `RailsConsent::ControllerHelpers`
+
+You can validate the shipped signatures locally with:
+
+```bash
+rbs -I sig validate
+```
+
 ## Storage Modes
 
 ### Signed Cookie Storage

data/{app/helpers → lib}/rails_consent/application_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RailsConsent
   module ApplicationHelper
     def rails_consent_assets

data/lib/rails_consent/version.rb

@@ -1,3 +1,3 @@
 module RailsConsent
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/rails_consent.rb

@@ -9,6 +9,8 @@ require "rails_consent/category_loader"
 require "rails_consent/cookie_store"
 require "rails_consent/preference_set"
 require "rails_consent/default_consent_resolver"
+require "rails_consent/controller_helpers"
+require "rails_consent/application_helper"
 require "rails_consent/engine"
 
 module RailsConsent

data/sig/manifest.yaml

@@ -0,0 +1 @@
+dependencies: []

data/sig/rails_consent.rbs

@@ -0,0 +1,107 @@
+module RailsConsent
+  type preference_value = bool | ::Integer
+  type consent_hash = ::Hash[::String, preference_value]
+
+  VERSION: ::String
+
+  class Error < ::StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  def self.configuration: () -> Configuration
+  def self.configuration=: (Configuration configuration) -> Configuration
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration configuration) -> void } -> true
+
+  class CookieDefinition
+    attr_reader name: ::String
+    attr_reader provider: ::String?
+    attr_reader purpose: ::String?
+
+    def initialize: (name: ::String | ::Symbol, ?provider: ::String?, ?purpose: ::String?) -> void
+  end
+
+  class Category
+    attr_reader description: ::String
+    attr_reader key: ::Symbol
+    attr_reader label: ::String
+    attr_reader cookies: ::Array[CookieDefinition]
+
+    def initialize: (
+      key: ::String | ::Symbol,
+      required: bool,
+      description: ::String?,
+      ?label: ::String?,
+      ?cookies: ::Array[untyped]
+    ) -> void
+
+    def required?: () -> bool
+  end
+
+  class CategoryLoader
+    def initialize: (?locale: ::String | ::Symbol) -> void
+    def categories: () -> ::Array[Category]
+    def category_keys: () -> ::Array[::String]
+  end
+
+  class Configuration
+    BANNER_POSITIONS: ::Array[::Symbol]
+    STORAGE_VALUES: ::Array[::Symbol]
+
+    attr_accessor banner_position: ::Symbol
+    attr_accessor cookie_destroyer: untyped
+    attr_accessor cookie_expiration_days: ::Integer
+    attr_accessor cookie_http_only: bool
+    attr_accessor cookie_name: ::String
+    attr_accessor cookie_path: ::String
+    attr_accessor cookie_reader: untyped
+    attr_accessor cookie_same_site: ::Symbol?
+    attr_accessor cookie_secure: untyped
+    attr_accessor cookie_writer: untyped
+    attr_accessor consent_recorded_provider: untyped
+    attr_accessor preferences_provider: untyped
+    attr_accessor preferences_destroyer: untyped
+    attr_accessor preferences_writer: untyped
+    attr_accessor prompt_dismissible: bool
+    attr_reader consent_resolver: untyped
+    attr_reader storage: ::Symbol
+
+    def initialize: () -> void
+    def consent_resolver=: (untyped value) -> untyped
+    def consent_resolver_configured?: () -> bool
+    def storage=: (::Symbol value) -> ::Symbol
+    def validate!: () -> true
+  end
+
+  module ControllerHelpers
+    def consent_given?: (::String | ::Symbol category_name) -> bool
+    def consent_preferences: () -> consent_hash
+    def consent_recorded?: () -> bool
+    def reset_consent!: () -> true
+  end
+
+  module ApplicationHelper
+    def rails_consent_assets: () -> ::String
+    def rails_consent_banner: (?position: ::Symbol?, ?dismissible: bool?) -> untyped
+    def rails_consent_preferences_button: (?untyped label, **untyped options) ?{ () -> untyped } -> untyped
+  end
+
+  class CookieStore
+    def self.read: (configuration: Configuration, cookies: untyped, categories: ::Array[Category], ?request: untyped) -> consent_hash
+    def self.write!: (configuration: Configuration, cookies: untyped, categories: ::Array[Category], preferences: untyped, request: untyped) -> consent_hash
+    def self.delete!: (configuration: Configuration, cookies: untyped, ?request: untyped) -> untyped
+  end
+
+  class DefaultConsentResolver
+    def call: (category: Category, preferences: ::Hash[::String | ::Symbol, untyped], **untyped options) -> bool
+  end
+
+  class PreferenceSet
+    TIMESTAMP_KEY: ::String
+
+    def initialize: (categories: ::Array[Category], source: untyped) -> void
+    def to_h: () -> consent_hash
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_consent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Dhairya Gabhawala
@@ -44,9 +44,7 @@ files:
 - app/assets/config/rails_consent_manifest.js
 - app/assets/javascripts/rails_consent.js
 - app/assets/stylesheets/rails_consent/application.css
-- app/controllers/concerns/rails_consent/controller_helpers.rb
 - app/controllers/rails_consent/preferences_controller.rb
-- app/helpers/rails_consent/application_helper.rb
 - app/views/rails_consent/_banner.html.erb
 - app/views/rails_consent/_category_toggle.html.erb
 - app/views/rails_consent/_cookie_table.html.erb
@@ -56,14 +54,18 @@ files:
 - lib/generators/rails_consent/install/templates/initializer.rb
 - lib/generators/rails_consent/install/templates/rails_consent.en.yml
 - lib/rails_consent.rb
+- lib/rails_consent/application_helper.rb
 - lib/rails_consent/category.rb
 - lib/rails_consent/category_loader.rb
 - lib/rails_consent/configuration.rb
+- lib/rails_consent/controller_helpers.rb
 - lib/rails_consent/cookie_store.rb
 - lib/rails_consent/default_consent_resolver.rb
 - lib/rails_consent/engine.rb
 - lib/rails_consent/preference_set.rb
 - lib/rails_consent/version.rb
+- sig/manifest.yaml
+- sig/rails_consent.rbs
 homepage: https://rails-consent.dhairyagabhawala.com/
 licenses:
 - MIT