# Changelog

All notable changes to the Jurislexr Backend project are 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]

### Planned Features

- Integration with external verification services
- Advanced matter tagging and filtering
- Bulk export operations
- Team collaboration tools (real-time updates)
- Custom field definitions per workspace

---

## [1.2.0] - 2026-08-31

### Added

#### User Registration & Validation

- **Two-name requirement**: Users must provide at least a first and second name during registration
    - New validation rule: `App\Rules\RequireTwoNames`
    - Validates minimum 2 name parts, each ≥2 characters
    - Accepts letters, spaces, hyphens, apostrophes, and periods
    - Improved error messaging with clear examples

#### Early Adopter Discount Program - Phase 2

- **Fixed remaining slots display**: Early adopter discount notifications now always show remaining slots
    - Slot availability properly read from env config (`EARLY_ADOPTER_PUBLIC_SLOTS`, `EARLY_ADOPTER_TESTER_RESERVED_SLOTS`)
    - Visual indicators: 🟢 for available slots, 🔴 for full
    - Includes total early adopter count in Slack notifications
    - Fixes issue where slot information was not displayed when discount was auto-claimed

#### Weekly User Reports

- **Friday scheduled user activity report**: New console command `send:friday-user-report`
    - Automatically runs every Friday at 02:00 UTC (low peak hours)
    - Reports include:
        - Total users and new signups this week
        - Active users (with logins this week)
        - User segmentation (early access testers, early adopters, standard users)
        - Active subscriptions and trial count
        - Email verification rate
    - Output logged to `storage/logs/friday-user-report.log`
    - Sent to configured Slack channel via `SlackNotifier`

### Enhanced

#### Documentation

- **README.md**: Added comprehensive sections:
    - User Registration & Validation (name requirements with examples)
    - Early Adopter Discount Program (Phase 1 & 2, slot allocation, configuration)
    - Scheduled Tasks (complete table with all 6 auto-tasks)
    - Early adopter program environment variables documented

- **docs/openapi.yaml**: Updated API specification:
    - `/auth/register` endpoint now documents Early Adopter Program behavior
    - `name` field fully documented with requirements and examples
    - Added 3 response examples (early access tester, early adopter, regular user)
    - Validation error examples for name field
    - Better descriptions of `acquisition_type` values

#### Slack Notifications

- Improved `sendEarlyAdopterRegistered()` to display remaining slots unconditionally
- Added total count of early adopters in notification footer

#### Configuration

- Early adopter program env variables now with proper type casting:
    - `EARLY_ADOPTER_DISCOUNT_PERCENTAGE` (int)
    - `EARLY_ADOPTER_DISCOUNT_TOTAL_SLOTS` (int)
    - `EARLY_ADOPTER_TESTER_RESERVED_SLOTS` (int)
    - `EARLY_ADOPTER_PUBLIC_SLOTS` (int)
    - `EARLY_ADOPTER_CLAIMING_WINDOW_DAYS` (int)
    - `EARLY_ADOPTER_DURATION_MONTHS` (int)

### Fixed

#### Early Adopter Program

- **Issue**: Remaining slots from env config were not being read or displayed in Slack notifications
    - Root cause: Slot info only showed when discount wasn't auto-claimed (negative condition logic)
    - Solution: Changed to always display slot information when available
    - Now properly reflects `getRemainingSlots('public')` from config

#### Name Validation

- **Issue**: Users could register with single names (e.g., "Jane") or single-letter parts (e.g., "J D")
    - Previous rule `ValidPersonName` only checked format, not structure
    - Solution: New rule `RequireTwoNames` enforces minimum 2 name parts with ≥2 characters each
    - Better error messages guide users on correct format

### Changed

#### Scheduler Configuration

- **routes/console.php**: Updated Friday user report scheduling
    - Uses `->fridays()->at('02:00')->withoutOverlapping()` for reliability
    - Prevents concurrent executions of the same task
    - Logs output to dedicated file

#### Imports

- **AuthController**: Replaced import
    - Removed: `use App\Rules\ValidPersonName;`
    - Added: `use App\Rules\RequireTwoNames;`

### Security

- Enhanced user data collection with stricter name validation
- Prevents edge cases with single-character names
- Improves data quality for internal reporting

### Testing

- Add test cases for `RequireTwoNames` rule:
    - Valid two-part names should pass
    - Single names should fail
    - Single-letter parts should fail
    - Non-ASCII names should pass
- Add test cases for Friday report generation:
    - Should only run on Fridays
    - Should generate correct statistics
    - Should format Slack message correctly

---

## [1.1.0] - 2026-08-16

### Added

#### Early Adopter Discount Program - Phase 1

- **Early access tester enrollment**: New users during testing window automatically receive:
    - Full Enterprise tier access (no charge)
    - 3-week testing period (configurable via env)
    - Auto-transition to Phase 2 discount eligibility
    - Welcome notification via email and Slack

#### Console Commands

- `early-adopter:assign-testers`: Auto-assign discount slots to eligible early access testers
    - Runs daily at 00:01 when early access period ends
    - Respects reserved slot allocation (20 tester slots)
    - Logs results for audit trail

#### Scheduled Tasks

- Daily early access expiry reminders (3 days before expiry)
- Daily early adopter program statistics to Slack
- Discount expiry warnings (30 days and 7 days before expiration)
- Hourly cleanup of expired early access subscriptions

#### Slack Integration

- `sendEarlyAccessTester()`: Notifications when testers register
    - Shows tier, expiry date, auto-transition message
    - Includes tester and total user count
    - Formatted with emoji and clear status

- `sendEarlyAdopterDiscountClaimed()`: Notifications when discounts are claimed
    - Shows source (tester transition or new signup)
    - Displays slot number and remaining slots
    - Includes early adopter count

#### Environment Configuration

- `EARLY_ACCESS_ENABLED`: Enable/disable early access program
- `EARLY_ACCESS_START_DATE`: Start date for early access window
- `EARLY_ACCESS_DURATION_WEEKS`: Duration of early access period (default: 3)
- `EARLY_ACCESS_TIER`: Tier granted during early access (default: enterprise)
- `EARLY_ACCESS_TRANSITION_TO_DISCOUNT`: Auto-transition testers to discount program
- `EARLY_ADOPTER_DISCOUNT_ENABLED`: Enable/disable discount claiming
- `EARLY_ADOPTER_DISCOUNT_PERCENTAGE`: Discount percentage (default: 30%)
- `EARLY_ADOPTER_DISCOUNT_START`: When discount claiming window opens
- `EARLY_ADOPTER_CLAIMING_WINDOW_DAYS`: How long claims remain open (default: 30 days)

### Enhanced

#### Database Models

- **User Model**: Added fields
    - `acquisition_type`: Track source (early_access_tester, early_adopter, standard)
    - `early_access_expires_at`: Expiry timestamp for early access tier
    - Query scopes for filtering by acquisition type

- **Subscription Model**: Added fields
    - `is_early_access`: Boolean flag for early access subscriptions
    - `early_access_expires_at`: Track expiry
    - Query methods for cleanup operations

- **EarlyAdopterProgram Model**: New model for discount tracking
    - Tracks discount claims, auto-assignments, slot numbers
    - Stores metadata and eligibility status
    - Supports both tester and public signup tracking

#### Services

- **EarlyAdopterProgramManager**: New service for program management
    - `isEarlyAccessActive()`: Check if testing window is open
    - `grantEarlyAccess()`: Award enterprise tier to testers
    - `isDiscountWindowOpen()`: Check if claiming window is open
    - `claimDiscount()`: Assign discount slot to user
    - `autoAssignTesterDiscounts()`: Batch-assign testers (scheduler)
    - `getSlotAvailability()`: Check remaining slots by type
    - `getRemainingSlots()`: Quick slot availability check
    - Caching for high-frequency availability checks

#### Notifications

- New email notification: `EarlyAccessGrantedNotification`
- New email notification: `EarlyAdopterDiscountAvailable`
- New email notification: `EarlyAdopterDiscountAutoAssigned`
- New email notification: `EarlyAccessExpiringNotification`
- New email notification: `EarlyAdopterDiscountExpiring`

### Changed

#### Registration Flow

- Registration response now includes:
    - `acquisition_type`: User's program eligibility
    - `early_access`: Active early access details (if applicable)
    - `early_adopter_discount`: Discount details (if claimed)

#### Database Transactions

- Registration wrapped in `DB::beginTransaction()`/`DB::commit()`
- Ensures atomicity of user, workspace, and early adopter program creation
- Proper rollback on any failure

### Documentation

#### README.md

- Added Early Adopter Discount Program section
- Documented configuration variables
- Console command reference
- Scheduled tasks table

#### API Documentation

- `POST /auth/register` updated with early adopter program details
- Response envelope documents early access and discount fields
- Error scenarios documented

---

## [1.0.0] - 2026-07-26

### Initial Release

#### Core Features

- **Authentication**
    - User registration with email verification
    - Login with Bearer token (Sanctum)
    - Password reset flow
    - Profile management

- **Workspaces**
    - Create and manage workspaces
    - Role-based access (owner, admin, member)
    - Workspace invitations (works for non-registered users)
    - Member management and role assignment

- **Matters** (Legal Case Files)
    - Create, read, update, delete matters
    - Matter items for document management
    - Matter members with role-based access
    - Matter research items tracking

- **Search**
    - Query external legal research API (cases, judges, statutes)
    - Caching for performance
    - Rate limiting (free: 15 queries/month)
    - Judge intelligence for case analysis

- **Subscriptions**
    - Free, Individual, Professional, Firm tiers
    - Paystack payment integration
    - Trial management
    - Query limit enforcement

- **Exports**
    - Bulk matter export to PDF/Excel
    - Export history and status tracking
    - Queued job processing

- **Verification**
    - Verification stamp on matters/items
    - Audit log with digital signatures
    - Compliance tracking

- **Billing & Compliance**
    - Subscription lifecycle management
    - Paystack webhook integration
    - Trust information (DPA, SOC2, etc.)

#### Database

- PostgreSQL 14+
- 15+ migrations for core schema
- Factories for testing

#### API Documentation

- OpenAPI 3.0 spec (docs/openapi.yaml)
- Full endpoint documentation
- Request/response examples
- Error code reference

#### Testing

- Pest test framework
- Feature and unit tests
- Test factories for all models

#### Development Tools

- Laravel IDE helper for IntelliSense
- Laravel Pint for code style
- Vite for asset compilation
- Concurrent development server setup

#### Email Notifications

- Verification email on signup
- Password reset email
- Subscription notifications
- SLA warnings for review queue
- Export completion emails

#### Console Commands

- `review:sla-check`: Daily SLA warning emails (08:00)
- `ide-helper:generate`: Generate IDE helper files
- Database seeders for development

---

## Migration Guide

### Upgrading from 1.1.0 to 1.2.0

#### Required Steps

1. Run migrations (none in this release)
2. No database schema changes required
3. Update `.env` if customizing early adopter settings
4. Restart queue worker for new Friday report

#### Breaking Changes

- None

#### Deprecated

- None

#### New Env Variables

All are optional with sensible defaults:

```env
EARLY_ADOPTER_DISCOUNT_PERCENTAGE=30
EARLY_ADOPTER_TESTER_RESERVED_SLOTS=20
EARLY_ADOPTER_PUBLIC_SLOTS=30
EARLY_ADOPTER_CLAIMING_WINDOW_DAYS=30
EARLY_ADOPTER_DURATION_MONTHS=12
```

#### New Console Commands

- `send:friday-user-report`: Weekly user report

#### New Validation Rules

- `RequireTwoNames`: Validates user names have first and second components

---

## Support & Contributing

For bug reports and feature requests, please refer to the main repository documentation.

When contributing, please:

1. Follow the existing code style (Laravel Pint)
2. Add tests for new features
3. Update this CHANGELOG in your PR
4. Update API documentation if endpoints change