agreements 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81d911005203680cbf4a2c85a8da0c4bec60c04c9094e3e35af19c8e4fb595d7
-  data.tar.gz: 67a34497cc8a10c5f2803745e28b45949eb0ef550aa951b57f08f588c1c809cb
+  metadata.gz: 921978d679f2c21c42fda41e4caa14e844e5fbfbb57a10c78738811441814547
+  data.tar.gz: 342464faa1422920f63ca881f7d64728d35e6b88c7e595d351a06c181a7692cd
 SHA512:
-  metadata.gz: 6f78483f20c53fdb31f4c0537c96016d216efb6b362ea35bdb8090752c6585a4ad76f19885cd81f051f55955d355bb58510edb0031266eef37bc32e89c45ed84
-  data.tar.gz: 6c64d27234a8d20e0bdece9b695ec67e3272da6df194abbe4f894490831f9659361e0891a3a70a38a2ed375e3caf773bacd13586fbc358381e53df39213ada35
+  metadata.gz: c1cf67625ad815b0e3df2033a609cd510cf9c4ca97888b518c842546bb174b3c22abfd7bfc2670d0756337c3e24465b2e70b4a52887dbbf7e0a1a9c7c78a939b
+  data.tar.gz: 60cd61c042671c9bcb86f1e2f3c37ceeba9bfa2600aee3082766fe8b2124a38a7c81bc3b7ae5328f65f6265d6ac8ac6ef2f77416cd3d28547fd1c70bb47607a3

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0 - 2026-11-12
+
+- Add an optional `effective_at` to versions, so a version can be inserted when
+  notice is given and become current on the date it takes effect. Requires a
+  new nullable column; see "Upgrading from 0.3" in the README.
+- Add `Agreements.upcoming_version` to show the next scheduled version.
+- Add `Agreements::TestHelper#accept_agreement` for host test suites.
+- Explain in the README what acceptance evidence does and does not prove.
+
 ## 0.3.0 - 2026-11-12
 
 - Answer pending non-HTML requests with `403 Forbidden` instead of letting them

data/README.md

@@ -29,6 +29,17 @@ view, initializer, JavaScript, CSS, or admin dashboard to integrate.
 
 Ruby >= 3.2 · Rails >= 7.1 and < 9 · PostgreSQL and SQLite
 
+### Upgrading from 0.3
+
+Version 0.4 adds a nullable `effective_at` column to `agreements_versions`:
+
+```bash
+bin/rails generate migration AddEffectiveAtToAgreementsVersions effective_at:datetime
+bin/rails db:migrate
+```
+
+Existing rows keep `effective_at` empty and stay in effect from their creation.
+
 ### Upgrading from 0.2
 
 Version 0.3 has no schema change. `require_agreement` now answers a pending
@@ -85,9 +96,44 @@ changes later. The final check stops a deploy if a version label already exists
 with different content: a deployed version must never change. Use the same
 create-then-check loop in your seeds.
 
-The newest inserted row for an agreement key is current immediately. There is
-no draft, publish, activate, or scheduling lifecycle. A correction or legal
-update is a new immutable row with a new version label.
+A version without `effective_at` is current as soon as it is inserted. There is
+no draft, publish or activate step. A correction or legal update is a new
+immutable row with a new version label.
+
+### Give notice before a version takes effect
+
+Terms often promise notice before a change applies, for example "at least 14
+days before the changes take effect". Insert the version when you send the
+notice, with the date it takes effect:
+
+```ruby
+VERSION = {
+  agreement_key: "user_terms",
+  version: "2026-12-01",
+  effective_at: Time.utc(2026, 12, 1),
+  # acceptance_statement, documents ...
+}.freeze
+```
+
+Until that time the previous version stays current, nobody is asked to accept,
+and `accept!` refuses the new version. From that time the new version is
+current and every subject who has not accepted it is pending. Show the notice
+in your app with:
+
+```ruby
+Agreements.upcoming_version("user_terms") # => the next scheduled version, or nil
+```
+
+The current version is the one that took effect most recently: its
+`effective_at`, or its creation time when `effective_at` is empty. When two
+versions take effect at the same time, the one inserted later wins.
+
+Subjects cannot accept a scheduled version early. Someone who accepts the
+current version during the notice period is asked again on the effective date.
+
+A scheduled version cannot have acceptances before it takes effect. To cancel
+it, delete it in a data migration with a migration-local model before its
+effective date. After that date it is evidence like any other version.
 
 Document references accept `title`, an HTTPS `url`, an optional 64-character
 `sha256`, and an optional `key`. Use `key` (lowercase letters, digits and
@@ -246,6 +292,29 @@ end
 When no version exists for a key, nothing is pending and nothing is blocked.
 Insert the first version before you rely on enforcement.
 
+## Test your application
+
+Once enforcement is on, most of your tests need subjects that have already
+accepted. Include the test helper:
+
+```ruby
+# test/test_helper.rb
+require "agreements/test_helper"
+
+class ActiveSupport::TestCase
+  include Agreements::TestHelper
+end
+```
+
+```ruby
+accept_agreement("user_terms", subject: user)
+accept_agreement("organization_dpa", subject: organization, actor: owner, authority: "organization_owner")
+```
+
+`accept_agreement` accepts the current version with its canonical statement and
+the `en` locale. It raises when no current version exists, so insert versions
+in your fixtures or setup first.
+
 ## Evidence model
 
 `agreements_versions` contains:
@@ -254,6 +323,7 @@ Insert the first version before you rely on enforcement.
 - human version label;
 - exact acceptance statement;
 - external document references and optional SHA-256 digests;
+- optional effective date;
 - timestamps.
 
 `agreements_acceptances` contains:
@@ -283,12 +353,43 @@ controls.
 
 1. Publish immutable/versioned legal-document URLs and any verified digests.
 2. Add the finished bundle to the host's seed registry.
-3. Add a host data migration that inserts the same immutable version.
-4. Deploy. The new row becomes current and subjects missing it are prompted.
+3. Add a host data migration that inserts the same immutable version, with
+   `effective_at` if your terms promise notice.
+4. Deploy. The new row becomes current at once, or on its effective date, and
+   subjects missing it are prompted.
 
 Production deployments normally run migrations, not seeds. Changing a seed
 registry alone does not deploy a new version to an existing installation.
 
+## What the evidence proves
+
+The gem records which version and which sentence a subject accepted, who did
+it, under what authority, and when. That is the part your application can
+prove later. Some questions it cannot answer for you:
+
+- **The whole page counts.** Courts look at the entire screen, not only the
+  checkbox. In *Berman v. Freedom Financial Network* (9th Cir. 2022) the terms
+  did not bind the user: the notice was small grey text, the links did not
+  look like links, and the button said "Continue" without saying that it meant
+  acceptance. Your layout, contrast and button text decide this. The gem does
+  not see them.
+- **It is not a qualified electronic signature.** Under eIDAS (Regulation (EU)
+  No 910/2014, Article 25), an electronic signature cannot be denied legal
+  effect only because it is electronic or not qualified. A checkbox is still
+  not a qualified electronic signature, and this gem does not create one.
+- **Acknowledging a privacy notice is not consent.** Under the GDPR you inform
+  people (Article 13). Consent (Articles 6 and 7) is a separate, specific and
+  withdrawable choice. Keep the two apart in your copy and your records.
+- **The text of your terms still matters.** In the EU, an unfair term in a
+  consumer contract does not bind the consumer (Directive 93/13/EEC), however
+  clearly it was accepted.
+- **Identity and authority are yours to check.** The gem stores the actor and
+  the authority you pass. It does not verify who the person is or whether they
+  may bind an organization.
+
+Your counsel decides what your agreements need. The gem keeps the record of
+what was accepted.
+
 ## Not this gem
 
 - Legal-document hosting, editing, rendering, uploads, or a CMS.
@@ -302,7 +403,9 @@ registry alone does not deploy a new version to an existing installation.
   layouts, routes, or copy.
 
 Those are real product categories. They are not prerequisites for proving an
-ordinary Terms or organization-DPA acceptance.
+ordinary Terms or organization-DPA acceptance. If you need consent withdrawal,
+signed receipts, request evidence or a form builder, look at
+[clickwrap](https://github.com/rameerez/clickwrap).
 
 ## Later, only after a concrete trigger
 

data/app/models/agreements/version.rb

@@ -17,8 +17,29 @@ module Agreements
     validates :version, :acceptance_statement, presence: true
     validate :documents_are_external_references
 
-    def self.current_for(agreement_key)
-      where(agreement_key: agreement_key).order(created_at: :desc, id: :desc).first
+    # Filtering by time in Ruby keeps the SQL identical, so the query cache
+    # serves repeated checks within a request. Each key has only a few versions.
+    def self.current_for(agreement_key, now: Time.current)
+      versions = where(agreement_key: agreement_key).to_a
+      versions.select { |version| version.in_effect?(now) }.max_by(&:precedence)
+    end
+
+    def self.upcoming_for(agreement_key, now: Time.current)
+      scheduled = where(agreement_key: agreement_key).to_a.reject { |version| version.in_effect?(now) }
+      next_from = scheduled.map(&:effective_from).min
+      scheduled.select { |version| version.effective_from == next_from }.max_by(&:precedence)
+    end
+
+    def precedence
+      [effective_from, created_at, id]
+    end
+
+    def effective_from
+      effective_at || created_at
+    end
+
+    def in_effect?(now = Time.current)
+      effective_from <= now
     end
 
     def accepted_by?(subject)

data/lib/agreements/test_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Agreements
+  module TestHelper
+    def accept_agreement(agreement_key, subject:, actor: subject, authority: "self", locale: "en")
+      version = Agreements.current_version(agreement_key)
+      raise ArgumentError, "no current #{agreement_key} version; insert one in your test setup" unless version
+
+      Agreements.accept!(
+        agreement_key,
+        version_id: version.id,
+        subject: subject,
+        actor: actor,
+        authority: authority,
+        acceptance_statement: version.acceptance_statement,
+        locale: locale
+      )
+    end
+  end
+end

data/lib/agreements/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agreements
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/agreements.rb

@@ -17,6 +17,10 @@ module Agreements
       Version.current_for(agreement_key)
     end
 
+    def upcoming_version(agreement_key)
+      Version.upcoming_for(agreement_key)
+    end
+
     def pending_version(agreement_key, subject:)
       current_version(agreement_key).then do |version|
         version unless version.nil? || version.accepted_by?(subject)

data/lib/generators/agreements/install/templates/create_agreements_tables.rb.tt

@@ -7,6 +7,7 @@ class CreateAgreementsTables < ActiveRecord::Migration<%= migration_version %>
       t.string :version, null: false
       t.text :acceptance_statement, null: false
       t.json :documents, null: false, default: []
+      t.datetime :effective_at
       t.timestamps
 
       t.index %i[agreement_key version], unique: true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agreements
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -108,6 +108,7 @@ files:
 - lib/agreements/errors.rb
 - lib/agreements/identity.rb
 - lib/agreements/recorder.rb
+- lib/agreements/test_helper.rb
 - lib/agreements/version.rb
 - lib/generators/agreements/install/install_generator.rb
 - lib/generators/agreements/install/templates/create_agreements_tables.rb.tt