feat(trials): add per-plan configurable trial periods with conversion (#1722)

[Clement-coder]

Summary

Resolves #1722. Trial length was hardcoded to 14 days for every plan. This PR makes it fully configurable per plan and adds automatic trial-to-paid conversion at expiry.

---

Changes

backend/subscription/domain/trialManagementService.ts

New: PlanTrialConfig interface

interface PlanTrialConfig {
  planId: string;
  trialDurationDays: number;   // must be > 0
  autoConvertOnExpiry: boolean;
  description?: string;
}

New methods on TrialManagementService

• registerPlanTrialConfig(config) — register or replace a plan's trial policy; validates trialDurationDays > 0
• getPlanTrialConfig(planId) — retrieve config; returns undefined if not registered
• listPlanTrialConfigs() — enumerate all registered configs

Updated: startTrial() — duration resolution order:

1. Explicit durationDays param (call-site override)
2. Registered PlanTrialConfig.trialDurationDays for the plan
3. DEFAULT_TRIAL_DURATION_DAYS (14) — global fallback, preserves all existing behaviour

Updated: processExpirations() — now returns { converted: TrialRecord[], expired: TrialRecord[] }:

• When a plan has autoConvertOnExpiry: true → sets status = 'converted', conversionTrigger = 'automatic_time_based', emits trial_converted + payment_completed events
• Otherwise → sets status = 'expired', emits trial_expired (previous behaviour)
• Trials not yet past endDate and already-terminal trials are skipped

backend/migrations/006_plan_trial_configs.sql

• plan_trial_configs table with plan_id FK, trial_duration_days CHECK (> 0), auto_convert_on_expiry, description, timestamps
• Auto-update trigger for updated_at
• @down rollback section
• Migration dry-run: 0 errors

backend/subscription/__tests__/trialManagementService.test.ts

• Fixed existing processExpirations test to destructure { expired, converted }
• Added 18 new tests covering all three acceptance criteria

---

Acceptance criteria

• Length configurable per plan (registerPlanTrialConfig + PlanTrialConfig.trialDurationDays)
• Converts to paid at expiry (processExpirations auto-converts when autoConvertOnExpiry: true)
• Tested (36/36 tests pass: 18 existing + 18 new)

Test output

Tests: 36 passed, 36 total

[drips-wave]

@Clement-coder Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits