# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [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:
```elixir
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](https://ash-hq.org/) by Zach Daniel and the Ash core team.
Inspired by [phx_cookie_consent](https://github.com/pzingg/phx_cookie_consent) (Ecto-based) but rewritten for Ash Framework.
### License
MIT License - See LICENSE file for details
---
[Unreleased]: https://github.com/shotleybuilder/ash_cookie_consent/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/shotleybuilder/ash_cookie_consent/releases/tag/v0.1.0
