Feat/sprw 3087/simplifying plan changes

[mayankjha-eng]

Description

Summary

Implemented Admin-controlled Hub subscription management APIs to allow administrators to extend trials, add plans, and change hub plans directly from the backend. These APIs simplify subscription management without requiring manual database updates or complex UI workflows.

What was implemented

1. Trial Extension API

• Added API to extend trial period for a specific hub.
• Validates hub existence and ensures the hub is currently in trial.
• Calculates the new trial end date based on extension days.
• Prevents trial extension beyond the configured maximum trial duration.
• Updates billing information and records the change for audit purposes.
• Sends trial extension notification email to hub users when enabled.

2. Backend Plan Addition API

• Added API to assign a subscription plan to a hub from the backend.
• Validates plan existence and ensures the hub does not already have the same plan.
• Calculates prorated billing amount when applicable.
• Updates hub subscription details and billing records.
• Logs the plan addition for audit tracking.
• Sends notification email informing users about the plan upgrade.

3. Plan Change API

• Added API to upgrade or downgrade a hub’s current plan.
• Validates the current and new plans.
• Ensures upgrade/downgrade rules are followed.
• Calculates price difference and proration when enabled.
• Updates subscription details and billing records.
• Sends confirmation email after the plan change.

Additional Improvements

• Added request validation using DTOs.
• Secured APIs using JWT authentication and role guards.
• Integrated email notifications for trial extensions and plan updates.
• Added Swagger/OpenAPI documentation to enable testing directly from API docs.
• Implemented audit logging for subscription changes.

APIs Added

• POST /api/admin/hubs/{hubId}/trial/extend
• POST /api/admin/hubs/{hubId}/plans/add
• PUT /api/admin/hubs/{hubId}/plan/change

Result

Admins can now manage hub subscriptions (trial extensions, plan additions, and plan changes) through dedicated APIs with proper validation, auditing, and notifications.

Add Issue Number

SPRW-3087

Add Screenshots/GIFs

Controlled.Hub.APIs.for.simplifying.Plan.Changes.mp4

Add Known Issue

If applicable, add any known issues.

Contribution Checklist:

• The pull request only addresses one issue or adds one feature.
• I have linked an issue to the pull request.
• I have linked a PR type label to the pull request.
• The pull request does not introduce any breaking changes
• I have added screenshots or gifs to help explain the change if applicable.
• I have read the contribution guidelines.

Note: Keeping the PR small and focused helps make it easier to review and merge. If you have multiple changes you want to make, please consider submitting them as separate pull requests.