Changelog

View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Quick Integration Checklist in usage-rules.md for rapid setup guidance

Changed

  • BREAKING DOCUMENTATION: Removed global hook pattern from getting-started guide
  • Updated all integration examples to use router-level live_session only
  • Removed general Phoenix/LiveView teaching from documentation (focused on consent integration)
  • Comprehensive extending guide improvements with real-world database sync patterns

Fixed

  • Documentation now clearly warns against global hook anti-pattern
  • Added guidance for when to skip LiveView hook on admin/authenticated routes
  • Added session interference prevention with skip_session_cache option
  • Extending guide now includes user ID extraction, "newer wins" logic, and proper user relationships

0.1.0 - 2025-11-04

Initial release of AshCookieConsent - GDPR-compliant cookie consent management for Ash Framework applications.

Added

Core Features

  • ConsentSettings Ash Resource with GDPR-compliant attributes:
    • terms - Policy version identifier
    • groups - Array of consented cookie categories
    • consented_at - Consent timestamp
    • expires_at - Consent expiration (365 days default)
  • Custom Ash Actions:
    • grant_consent - Record user consent with automatic timestamps
    • revoke_consent - Revoke all consent
    • active_consents - Query non-expired consents
  • Validations: Terms and groups validation with clear error messages

Phoenix Components

  • ConsentModal component with:
    • AlpineJS-powered interactive modal
    • Tailwind CSS styling (customizable)
    • Granular cookie group selection
    • Accept All / Reject All shortcuts
    • Keyboard navigation (Escape to close)
    • Click-outside dismissal
    • Accessibility support (ARIA labels, focus management)
  • ConsentScript component for conditional script loading:
    • Only load scripts when user has consented to category
    • Support for async/defer attributes
    • Custom attributes pass-through
    • Examples for Google Analytics, Tag Manager, Facebook Pixel

Integration Layer

  • AshCookieConsent.Plug for traditional Phoenix apps:
    • Loads consent from three-tier storage
    • Sets assigns (:consent, :show_consent_modal, :cookie_groups)
    • Configurable cookie and session keys
    • Optional database sync for authenticated users
  • AshCookieConsent.LiveView.Hook for LiveView apps:
    • on_mount callback with :load_consent and :require_consent phases
    • Socket assign management
    • Event handlers for consent updates
    • Helper functions (show_modal/1, hide_modal/1)
  • Three-Tier Storage System (AshCookieConsent.Storage):
    • Read Priority: assigns → session → cookie → database
    • Write Strategy: All tiers updated simultaneously
    • Automatic sync on login for authenticated users
    • Conflict resolution (newest consent wins)
  • Cookie Management (AshCookieConsent.Cookie):
    • Signed cookies using Phoenix.Token
    • JSON encoding with automatic timestamp handling
    • Configurable cookie options (max_age, domain, path, etc.)
    • HttpOnly, Secure, SameSite defaults

Helper Functions

  • consent_given?/2 - Check if user consented to cookie group
  • get_consent/1 - Retrieve current consent data
  • has_consent?/1 - Check if any consent exists
  • Cookie group configuration via Application config

Documentation

  • README.md with:
    • Badges (Hex.pm, documentation, license)
    • "Why AshCookieConsent?" comparison section
    • Quick 4-line integration example
    • Feature comparison table vs alternatives
  • 6 Comprehensive Guides (1,820+ lines total):
    • getting-started.md - Installation and basic setup
    • migration-guide.md - Migration from other libraries and adding to existing apps
    • examples.md - Real-world integration patterns
    • troubleshooting.md - Common issues and solutions
    • extending.md - Custom storage, UI customization
    • usage-rules.md - AI assistant integration guidance
  • Code Documentation: All modules and public functions documented with examples
  • Moduledoc and @doc coverage for all public APIs

Testing

  • 163 Comprehensive Tests including:
    • Unit tests for Ash resource (ConsentSettings)
    • Component rendering tests
    • Cookie encoding/decoding tests
    • Plug integration tests
    • LiveView Hook tests
    • Three-tier storage tests
    • Helper function tests
    • Edge case coverage (expiration, malformed data, etc.)
  • All tests passing with 0 failures

Code Quality

  • Credo: Passing strict mode (intentional TODOs documented)
  • Dialyzer: Zero type warnings (0 errors)
  • Formatted: Using mix format
  • Zero compile warnings
  • Documented extension points for database sync

Design Decisions

Database Sync - Intentionally Optional

The library provides extension points for database synchronization but doesn't enforce a specific user relationship pattern. This allows:

  • Cookie/session storage works for all users (authenticated or not)
  • Apps can add user relationships as needed
  • Flexibility in user model architecture
  • Simple integration without database requirements

Extension Points:

  • lib/ash_cookie_consent/storage.ex: Stubbed load_user_consent/2 and save_user_consent/3
  • lib/ash_cookie_consent/plug.ex: Stubbed database sync functions
  • lib/ash_cookie_consent/live_view/hook.ex: Stubbed save_consent_to_db/3

See guides/migration-guide.md section "Adding User Relationships" for complete implementation guide.

Three-Tier Storage Benefits

  • Assigns: Fastest access, request-scoped
  • Session: Server-side cache, no database roundtrip
  • Cookie: Client-side persistence, works offline
  • Database: Audit trail, cross-device sync (when implemented)

Dependencies

Required

  • ash ~> 3.0 - Core Ash Framework
  • phoenix ~> 1.7 - Phoenix Framework
  • phoenix_live_view ~> 1.0 - LiveView support
  • jason ~> 1.4 - JSON encoding

Optional

  • ash_postgres ~> 2.0 - PostgreSQL data layer (or use ash_sqlite)

Development

  • ex_doc ~> 0.34 - Documentation generation
  • credo ~> 1.7 - Static analysis
  • dialyxir ~> 1.4 - Type checking

Configuration

Default cookie groups:

config :ash_cookie_consent, :cookie_groups, [
  %{
    key: "essential",
    label: "Essential Cookies",
    description: "Required for the website to function",
    required: true
  },
  %{
    key: "analytics",
    label: "Analytics Cookies",
    description: "Help us understand how visitors use our website",
    required: false
  },
  %{
    key: "marketing",
    label: "Marketing Cookies",
    description: "Used to deliver personalized advertisements",
    required: false
  }
]

Migration Path

For existing applications:

  1. Add dependency to mix.exs
  2. Create ConsentSettings resource with data layer
  3. Add Plug to router (after :fetch_session)
  4. Add LiveView Hook (optional, for LiveView apps)
  5. Add modal component to layout
  6. Configure cookie groups

See guides/migration-guide.md for detailed instructions.

Breaking Changes

None (initial release)

Known Limitations

  • Database sync requires user relationship: Apps must implement user relationship and database queries (documented extension points provided)
  • AlpineJS required: Modal interactivity requires AlpineJS v3.x
  • Tailwind recommended: Components styled with Tailwind (customizable via Alpine x-bind)
  • Phoenix 1.7+: Requires Phoenix 1.7 for Phoenix.Component

Roadmap

See GitHub Issues for planned enhancements:

  • Built-in database sync helpers (v0.2.0)
  • Multi-language support
  • Consent banner variants (banner, modal, corner popup)
  • Export/import consent data
  • Enhanced analytics integration

Credits

Built with Ash Framework by Zach Daniel and the Ash core team.

Inspired by phx_cookie_consent (Ecto-based) but rewritten for Ash Framework.

License

MIT License - See LICENSE file for details