Feature/issue 929 trial management

[Tekgodfrey]

Description

This PR implements Subscription Trial Management with Conversion Optimization across the Node.js backend and the Soroban smart contract, resolving Issue #929.

Key Changes

Closes #929

Smart Contract Integration (contracts/subscription & contracts/types)

• Trialing Status: Added a Trialing status to the SubscriptionStatus enum to differentiate trials from fully active and billed subscriptions.
• Trial Config Storage: Defined a new TrialConfig struct and introduced a PlanTrial(u64) variant in the StorageKey enum. This allows us to link trial settings to a plan without modifying the existing Plan struct signature, ensuring backward compatibility with existing storage entries.
• Trial Module: Introduced contracts/subscription/src/trial.rs which provides set_plan_trial and get_plan_trial to configure a plan's trial duration. These endpoints are exported in the primary SubTrackrSubscription block (lib.rs).
• Subscription Lifecycle Updates: Updated the core subscribe method. If a plan has an active trial configuration, the resulting subscription starts with SubscriptionStatus::Trialing, and next_charge_at is correctly deferred until the end of the trial period instead of the standard billing interval.

Backend Integration (backend/services/billing)

• Trial Management Service: Added TrialManagementService (trialService.ts) to handle conversion optimizations.
  • Implemented checkTrialsEndingSoon, which scans subscriptions and emits trial_ending_soon webhook alerts for subscribers nearing their trial end date (e.g. within a 3-day threshold) to prompt conversion reminders or discounts.
  • Added processExpiredTrials to batch-process trials that have reached their next_charge_at timestamp.
  • Added getTrialAnalytics to track and measure the conversion rate of trials to paid subscriptions.
• Exports: Properly exported the service, types, and logic through backend/services/billing/index.ts.

Testing & Validation

• Unit Tests: Authored robust unit tests in backend/services/billing/__tests__/trialService.test.ts to validate threshold alerting, expired trial processing, and correct analytics reporting.
• Contract Tests: Verified structural integrity and logic paths using cargo check inside the contracts/subscription directory. (Note: local environment issues with the upstream soroban-sdk toolchain block full local cargo test execution, but the logic changes are syntactically and architecturally complete).

This PR will not be mergeable until all quality gates pass.

[drips-wave]

@Tekgodfrey 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