feat(controlplane): cloud and self-hosted billing trials with dashboard UX (#2701)

* feat(billing): cloud and self-hosted trials with billing UX

Trial start, cap activation, checkout flows, and dashboard billing pages.
Provisional license_data seeding with project_limit enforcement during trial
propagation. Removes local convoy-qa-ui.sh from tracking.

* feat(dashboard): map served self-hosted plan keys for billing catalog

alias overwatch catalog keys (business_annual, enterprise) onto canonical presentation keys so feature cards and trial filtering work with the env-driven maple plan allowlist.

* fix(dashboard): drop unused trial-offer lint imports

* fix(billing): address bugbot trial poll, 4xx status, org pagination

Stop trial-cap polling on paid authoritative payloads that omit
daily_event_limit, forward definitive billing 4xx to clients, and
paginate all user orgs when resolving org_limit.

* fix(billing): resolve asynq licenser at request time and trial subscribe label

RequireAsynqMonitoring reads the shared licenser per request so a self-hosted
trial refresh unlocks queue monitoring without restart. During trial, billing
CTA shows Subscribe now instead of Resubscribe when checkout_license_key exists.

* fix(dashboard): resolve catalog plan for self-hosted trial conversion

Trial convert sends the purchasable catalog plan id and cadence to upgrade
checkout instead of the trial subscription legacy plan row.

* fix(dashboard): normalize subscription plan for plansMatch in trial conversion

Add optional key on SubscriptionPlan and pass a normalized match object so
convertTrialToPaid resolves the catalog plan without TS2345.

* fix(controlplane): skip asynqmon routes when queue is not RedisQueue

Keep per-request RequireAsynqMonitoring for runtime trial unlock, but use
a safe type assertion so mock or alternate Queuer implementations can boot.

* fix(billing): defer trial supersede until mint succeeds

Call billing before mutating checkout state, record orphan failed trial
attempts without touching an active paid checkout, and treat post-write
license refresh as best-effort so mint retries are not triggered.

* fix(billing): persist checkout supersession before trial finalize

Write superseded attempt bookkeeping and active trial attempt id before
CompleteCheckoutIfActive so a pending paid checkout is cleared when trial
mint succeeds.

* fix(billing): recover locally when trial mint settles after billing

If Overwatch returns a trial license but checkout settlement fails, persist
the minted key via UpdateInstanceBillingConfig instead of returning an error
that leaves an orphan trial and blocks retry.

Author: mekilis

api/api.go

@@ -27,6 +27,7 @@ import (
 	"github.com/frain-dev/convoy/internal/organisation_members"
 	"github.com/frain-dev/convoy/internal/organisations"
 	"github.com/frain-dev/convoy/internal/pkg/billing"
+	"github.com/frain-dev/convoy/internal/pkg/license"
 	"github.com/frain-dev/convoy/internal/pkg/metrics"
 	"github.com/frain-dev/convoy/internal/pkg/middleware"
 	redisqueue "github.com/frain-dev/convoy/queue/redis"
@@ -194,6 +195,10 @@ func NewApplicationHandler(a *types.APIOptions) (*ApplicationHandler, error) {
 	}
 	ensureAPIRepositories(a)
 
+	if a.TrialEvents == nil {
+		a.TrialEvents = license.NewTrialEventLimiter(a.Redis, a.Logger)
+	}
+
 	appHandler := &ApplicationHandler{A: a}
 
 	cfg, err := config.Get()
@@ -203,7 +208,7 @@ func NewApplicationHandler(a *types.APIOptions) (*ApplicationHandler, error) {
 
 	appHandler.cfg = cfg
 
-	// Resolve the billing service URL: OSS/self-hosted default to prod Overwatch
+	// Resolve the billing service URL: OSS/self-hosted default to prod billing
 	// so catalog/checkout/license management work out of the box, while cloud
 	// (API key set) keeps requiring an explicit URL (Billing.Validate fails closed
 	// otherwise). The API key, not the URL, remains the cloud/org-billing signal
@@ -475,7 +480,10 @@ func (a *ApplicationHandler) mountControlPlaneRoutes(router chi.Router, handler
 		uiRouter.Use(middleware.JsonResponse)
 		uiRouter.Use(chiMiddleware.Maybe(middleware.RequireAuth(handler.A.Logger), shouldAuthRoute))
 
-		uiRouter.Get("/license/features", handler.GetLicenseFeatures)
+		// Guest-listed (login/signup fetch instance features pre-auth), but a signed-in
+		// dashboard call carries a bearer token; resolve it so the handler can count the
+		// caller's orgs and gate org_limit. Without this the org gate always fails open.
+		uiRouter.With(middleware.OptionalAuth(handler.A.Logger)).Get("/license/features", handler.GetLicenseFeatures)
 
 		uiRouter.Post("/users/forgot-password", handler.ForgotPassword)
 		uiRouter.Post("/users/reset-password", handler.ResetPassword)
@@ -721,7 +729,9 @@ func (a *ApplicationHandler) mountControlPlaneRoutes(router chi.Router, handler
 			billingRouter.Get("/tax_id_types", billingHandler.GetTaxIDTypes)
 			billingRouter.Post("/sh_checkout/start", billingHandler.StartSelfHostedCheckout)
 			billingRouter.Post("/sh_checkout/complete", billingHandler.CompleteSelfHostedCheckout)
+			billingRouter.Post("/sh_trial/start", billingHandler.StartSelfHostedTrial)
 			billingRouter.Get("/sh_subscription", billingHandler.GetSelfHostedSubscription)
+			billingRouter.Put("/sh_subscription/upgrade", billingHandler.UpgradeSelfHostedSubscription)
 			billingRouter.Delete("/sh_subscription", billingHandler.DeleteSelfHostedSubscription)
 			billingRouter.Get("/sh_organisation", billingHandler.GetSelfHostedOrganisation)
 			billingRouter.Put("/sh_tax_id", billingHandler.UpdateSelfHostedOrganisationTaxID)
@@ -751,6 +761,7 @@ func (a *ApplicationHandler) mountControlPlaneRoutes(router chi.Router, handler
 				billingRouter.Route("/organisations/{orgID}/subscriptions", func(billingSubRouter chi.Router) {
 					billingSubRouter.Get("/", billingHandler.GetSubscriptions)
 					billingSubRouter.Post("/onboard", billingHandler.OnboardSubscription)
+					billingSubRouter.Post("/trial", billingHandler.StartTrial)
 					billingSubRouter.Put("/{subscriptionID}/upgrade", billingHandler.UpgradeSubscription)
 					billingSubRouter.Delete("/{subscriptionID}", billingHandler.DeleteSubscription)
 				})
@@ -863,25 +874,27 @@ func (a *ApplicationHandler) mountControlPlaneRoutes(router chi.Router, handler
 		})
 	})
 
-	if a.A.Licenser.AsynqMonitoring() {
-		router.Route("/queue", func(asynqRouter chi.Router) {
-			asynqRouter.Group(func(sessionRouter chi.Router) {
-				sessionRouter.Use(middleware.RequireAuth(handler.A.Logger))
-				sessionRouter.Post("/monitoring/session", handler.CreateQueueMonitoringSession)
-				sessionRouter.Delete("/monitoring/session", handler.RevokeQueueMonitoringSession)
-			})
+	router.Route("/queue", func(asynqRouter chi.Router) {
+		asynqRouter.Use(middleware.RequireAsynqMonitoring(func() license.Licenser { return a.A.Licenser }, handler.A.Logger))
+		asynqRouter.Group(func(sessionRouter chi.Router) {
+			sessionRouter.Use(middleware.RequireAuth(handler.A.Logger))
+			sessionRouter.Post("/monitoring/session", handler.CreateQueueMonitoringSession)
+			sessionRouter.Delete("/monitoring/session", handler.RevokeQueueMonitoringSession)
+		})
 
-			rq := a.A.Queue.(*redisqueue.RedisQueue)
-			asynqRouter.Group(func(embedRouter chi.Router) {
-				embedRouter.Use(middleware.RequireQueueSessionCookie(handlers.ValidateQueueSessionCookie(handler.A.Redis, handler.A.Cache)))
-				embedRouter.Handle("/monitoring/embed/*", rq.MonitorWithRootPath("/queue/monitoring/embed"))
-			})
-			asynqRouter.Group(func(monitorRouter chi.Router) {
-				monitorRouter.Use(middleware.RequireAuth(handler.A.Logger))
-				monitorRouter.Handle("/monitoring/*", rq.Monitor())
-			})
+		rq, ok := a.A.Queue.(*redisqueue.RedisQueue)
+		if !ok {
+			return
+		}
+		asynqRouter.Group(func(embedRouter chi.Router) {
+			embedRouter.Use(middleware.RequireQueueSessionCookie(handlers.ValidateQueueSessionCookie(handler.A.Redis, handler.A.Cache)))
+			embedRouter.Handle("/monitoring/embed/*", rq.MonitorWithRootPath("/queue/monitoring/embed"))
 		})
-	}
+		asynqRouter.Group(func(monitorRouter chi.Router) {
+			monitorRouter.Use(middleware.RequireAuth(handler.A.Logger))
+			monitorRouter.Handle("/monitoring/*", rq.Monitor())
+		})
+	})
 
 	router.HandleFunc("/metrics", a.metricsHandler())
 }