Merge pull request #2735 from helixml/feat/wallet-plan-override

feat(quota): admin-granted paid plans via wallet PlanOverride (no Stripe)

Author: lukemarsden

api/pkg/quota/quota.go

@@ -60,6 +60,12 @@ func (m *DefaultQuotaManager) getOrgQuotas(ctx context.Context, orgID string) (*
 			MaxSpecTasks:          -1,
 		}
 	// Active subscription
+	// Admin plan override (paid out-of-band; independent of Stripe, so it's
+	// never reverted by a webhook). Takes precedence over the subscription.
+	case wallet.PlanOverride == types.PlanOverridePro:
+		quotas = m.getProQuotas()
+	case wallet.PlanOverride == types.PlanOverrideFree:
+		quotas = m.getFreeQuotas()
 	case wallet.StripeSubscriptionID != "" && wallet.IsSubscriptionActive():
 		// Paid plan limits
 		quotas = m.getProQuotas()
@@ -130,6 +136,12 @@ func (m *DefaultQuotaManager) getUserQuotas(ctx context.Context, userID string)
 			MaxRepositories:       -1,
 			MaxSpecTasks:          -1,
 		}
+	// Admin plan override (paid out-of-band; independent of Stripe, so it's
+	// never reverted by a webhook). Takes precedence over the subscription.
+	case wallet.PlanOverride == types.PlanOverridePro:
+		quotas = m.getProQuotas()
+	case wallet.PlanOverride == types.PlanOverrideFree:
+		quotas = m.getFreeQuotas()
 	case wallet.StripeSubscriptionID != "" && wallet.IsSubscriptionActive():
 		// Paid plan limits
 		quotas = m.getProQuotas()

api/pkg/quota/quota_test.go

@@ -161,6 +161,29 @@ func (s *QuotaManagerSuite) TestGetQuotas_UserTrialingGetsProQuotas() {
 	s.Equal(20, resp.MaxProjects)
 }
 
+// An admin PlanOverride="pro" grants Pro with NO Stripe subscription at all —
+// the out-of-band-paid-customer case.
+func (s *QuotaManagerSuite) TestGetQuotas_PlanOverrideProGrantsProWithoutSub() {
+	w := &types.Wallet{UserID: "user1", PlanOverride: types.PlanOverridePro}
+	s.expectUserQuotaDefaults("user1", w, enforceQuotasSettings())
+
+	resp, err := s.manager.GetQuotas(context.Background(), &types.QuotaRequest{UserID: "user1"})
+	s.NoError(err)
+	s.Equal(5, resp.MaxConcurrentDesktops, "PlanOverride=pro grants Pro without any subscription")
+}
+
+// PlanOverride="free" forces Free even when an active subscription exists
+// (override takes precedence over the Stripe-derived tier).
+func (s *QuotaManagerSuite) TestGetQuotas_PlanOverrideFreeBeatsActiveSub() {
+	w := proWallet("user1")
+	w.PlanOverride = types.PlanOverrideFree
+	s.expectUserQuotaDefaults("user1", w, enforceQuotasSettings())
+
+	resp, err := s.manager.GetQuotas(context.Background(), &types.QuotaRequest{UserID: "user1"})
+	s.NoError(err)
+	s.Equal(2, resp.MaxConcurrentDesktops, "PlanOverride=free forces Free even with an active sub")
+}
+
 func (s *QuotaManagerSuite) TestGetQuotas_UserQuotasDisabled() {
 	s.expectUserQuotaDefaults("user1", freeWallet("user1"), disabledQuotasSettings())
 

api/pkg/server/admin_org_handlers.go

@@ -1,13 +1,69 @@
 package server
 
 import (
+	"encoding/json"
 	"net/http"
 
+	"github.com/gorilla/mux"
 	"github.com/helixml/helix/api/pkg/store"
 	"github.com/helixml/helix/api/pkg/types"
 	"github.com/rs/zerolog/log"
 )
 
+// SetOrgPlanRequest is the body for POST /admin/orgs/{id}/plan.
+type SetOrgPlanRequest struct {
+	// Plan: "pro" | "free" forces the org's quota tier independent of Stripe
+	// (for customers who paid out-of-band). "" clears the override and reverts
+	// to the Stripe-derived tier.
+	Plan string `json:"plan"`
+}
+
+// adminSetOrgPlan godoc
+// @Summary Set an organization's plan override (admin only)
+// @Description Force an org's quota tier independent of Stripe — for customers who paid out-of-band. plan: "pro" | "free" | "" (clear). Never reverted by a Stripe webhook.
+// @Tags    organizations
+// @Param id path string true "Organization ID"
+// @Param request body SetOrgPlanRequest true "Plan override"
+// @Success 200 {object} types.Wallet
+// @Router /api/v1/admin/orgs/{id}/plan [post]
+// @Security BearerAuth
+func (apiServer *HelixAPIServer) adminSetOrgPlan(rw http.ResponseWriter, r *http.Request) {
+	orgID := mux.Vars(r)["id"]
+	if orgID == "" {
+		http.Error(rw, "organization id is required", http.StatusBadRequest)
+		return
+	}
+	var body SetOrgPlanRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		http.Error(rw, "invalid request body: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	switch body.Plan {
+	case "", types.PlanOverridePro, types.PlanOverrideFree:
+	default:
+		http.Error(rw, "plan must be one of: pro, free, or empty", http.StatusBadRequest)
+		return
+	}
+
+	adminUser := getRequestUser(r)
+	wallet, err := apiServer.getOrCreateWallet(r.Context(), adminUser, orgID)
+	if err != nil {
+		log.Err(err).Str("org_id", orgID).Msg("failed to get/create org wallet")
+		http.Error(rw, "failed to get org wallet: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+	wallet.PlanOverride = body.Plan
+	updated, err := apiServer.Store.UpdateWallet(r.Context(), wallet)
+	if err != nil {
+		log.Err(err).Str("org_id", orgID).Msg("failed to update org wallet plan override")
+		http.Error(rw, "Internal server error: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+	log.Info().Str("admin_id", adminUser.ID).Str("org_id", orgID).Str("plan", body.Plan).
+		Msg("admin set org plan override")
+	writeResponse(rw, updated, http.StatusOK)
+}
+
 // adminListOrganizations godoc
 // @Summary List organizations with wallets (admin only)
 // @Description List all organizations

api/pkg/server/admin_trial_handlers.go

@@ -27,6 +27,10 @@ const (
 type ActivateTrialRequest struct {
 	Days    int     `json:"days"`
 	Credits float64 `json:"credits"`
+	// Plan selects what to grant. "pro" grants a PAID plan via a PlanOverride
+	// (no Stripe subscription) — for customers who paid out-of-band (bank
+	// transfer). Empty or "trial" uses the Stripe trial path (Days applies).
+	Plan string `json:"plan,omitempty"`
 }
 
 // ActivateTrialResponse describes the outcome of a trial activation.
@@ -129,6 +133,41 @@ func (s *HelixAPIServer) consumeUserTrialIntent(ctx context.Context, user *types
 		Msg(fmt.Sprintf("admin-granted trial subscription created for %d days", days))
 }
 
+// consumeUserPlanOnFirstOrg applies any admin-stashed paid-plan intent
+// (PlanOnFirstOrg) to the given org's wallet as a PlanOverride. Called after an
+// org is created. Best-effort: errors are logged, never block org creation.
+// Independent of the Stripe trial path — a paid out-of-band grant needs no
+// subscription.
+func (s *HelixAPIServer) consumeUserPlanOnFirstOrg(ctx context.Context, user *types.User, orgID string) {
+	if user == nil || user.PlanOnFirstOrg == nil || *user.PlanOnFirstOrg == "" {
+		return
+	}
+	plan := *user.PlanOnFirstOrg
+
+	wallet, err := s.getOrCreateWallet(ctx, user, orgID)
+	if err != nil {
+		log.Warn().Err(err).Str("user_id", user.ID).Str("org_id", orgID).
+			Msg("failed to get/create wallet for plan-override consumption")
+		return
+	}
+	wallet.PlanOverride = plan
+	if _, err := s.Store.UpdateWallet(ctx, wallet); err != nil {
+		log.Warn().Err(err).Str("wallet_id", wallet.ID).
+			Msg("failed to persist plan override to wallet")
+		return
+	}
+
+	user.PlanOnFirstOrg = nil
+	if _, err := s.Store.UpdateUser(ctx, user); err != nil {
+		log.Warn().Err(err).Str("user_id", user.ID).
+			Msg("failed to clear PlanOnFirstOrg after consumption")
+		return
+	}
+
+	log.Info().Str("user_id", user.ID).Str("org_id", orgID).Str("plan", plan).
+		Msg("admin-stashed paid plan applied to first org wallet")
+}
+
 // adminActivateTrial godoc
 // @Summary Activate a trial for a user (Admin, cloud only)
 // @Description Stash a trial intent on the user, or immediately create a Stripe trial subscription on the user's oldest-owned org. Days defaults to 90; credits are taken verbatim from the request (0 means no admin top-up beyond what Stripe's subscription invoice contributes).
@@ -186,6 +225,46 @@ func (apiServer *HelixAPIServer) adminActivateTrial(_ http.ResponseWriter, req *
 		return nil, system.NewHTTPError500("failed to list user organizations: " + err.Error())
 	}
 
+	// Paid plan granted out-of-band (e.g. bank transfer): set a PlanOverride,
+	// no Stripe subscription. Independent of Stripe so it is never reverted by
+	// a webhook. Applied to the oldest owned org now, or stashed for the user's
+	// first org.
+	if body.Plan == types.PlanOverridePro {
+		if oldestOrg == nil {
+			plan := types.PlanOverridePro
+			targetUser.PlanOnFirstOrg = &plan
+			if body.Credits > 0 {
+				c := body.Credits
+				targetUser.PendingAdminCreditsOnFirstOrg = &c
+			}
+			updated, uErr := apiServer.Store.UpdateUser(ctx, targetUser)
+			if uErr != nil {
+				return nil, system.NewHTTPError500("failed to stash paid-plan intent: " + uErr.Error())
+			}
+			log.Info().Str("admin_id", adminUser.ID).Str("target_user_id", targetUserID).
+				Msg("admin stashed paid-plan intent on user (no org yet)")
+			return &ActivateTrialResponse{User: updated, Status: "stashed"}, nil
+		}
+		wallet, wErr := apiServer.getOrCreateWallet(ctx, targetUser, oldestOrg.ID)
+		if wErr != nil {
+			return nil, system.NewHTTPError500("failed to get wallet for oldest owned org: " + wErr.Error())
+		}
+		wallet.PlanOverride = types.PlanOverridePro
+		if _, wErr := apiServer.Store.UpdateWallet(ctx, wallet); wErr != nil {
+			return nil, system.NewHTTPError500("failed to set plan override: " + wErr.Error())
+		}
+		if body.Credits > 0 {
+			if _, bErr := apiServer.Store.UpdateWalletBalance(ctx, wallet.ID, body.Credits, types.TransactionMetadata{
+				TransactionType: types.TransactionTypeSubscription,
+			}); bErr != nil {
+				log.Warn().Err(bErr).Str("wallet_id", wallet.ID).Msg("failed to top up wallet with credits")
+			}
+		}
+		log.Info().Str("admin_id", adminUser.ID).Str("target_user_id", targetUserID).Str("org_id", oldestOrg.ID).
+			Msg("admin granted paid plan (PlanOverride=pro) on oldest owned org")
+		return &ActivateTrialResponse{User: targetUser, OrgID: oldestOrg.ID, Status: "applied"}, nil
+	}
+
 	// Path A: no owned org yet. Stash intent on the user; consumeUserTrialIntent
 	// will apply it when they create their first org.
 	if oldestOrg == nil {

api/pkg/server/docs.go

@@ -743,6 +743,46 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/v1/admin/orgs/{id}/plan": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Force an org's quota tier independent of Stripe — for customers who paid out-of-band. plan: \"pro\" | \"free\" | \"\" (clear). Never reverted by a Stripe webhook.",
+                "tags": [
+                    "organizations"
+                ],
+                "summary": "Set an organization's plan override (admin only)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Organization ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Plan override",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/server.SetOrgPlanRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/types.Wallet"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/admin/users/{id}": {
             "delete": {
                 "security": [
@@ -23094,6 +23134,10 @@ const docTemplate = `{
                 },
                 "days": {
                     "type": "integer"
+                },
+                "plan": {
+                    "description": "Plan selects what to grant. \"pro\" grants a PAID plan via a PlanOverride\n(no Stripe subscription) — for customers who paid out-of-band (bank\ntransfer). Empty or \"trial\" uses the Stripe trial path (Days applies).",
+                    "type": "string"
                 }
             }
         },
@@ -24970,6 +25014,15 @@ const docTemplate = `{
                 }
             }
         },
+        "server.SetOrgPlanRequest": {
+            "type": "object",
+            "properties": {
+                "plan": {
+                    "description": "Plan: \"pro\" | \"free\" forces the org's quota tier independent of Stripe\n(for customers who paid out-of-band). \"\" clears the override and reverts\nto the Stripe-derived tier.",
+                    "type": "string"
+                }
+            }
+        },
         "server.SharePointSiteResolveRequest": {
             "type": "object",
             "properties": {
@@ -36870,6 +36923,10 @@ const docTemplate = `{
                     "description": "PendingAdminCreditsOnFirstOrg holds credits stashed by admin via the\n/admin/users/{id}/credits endpoint when the user has no owned org yet.\nConsumed by consumeUserAdminCredits on first owned org, then cleared.\nKept separate from TrialCreditsOnFirstOrg so admins can comp credits\nwithout entangling the grant with trial-state UI or revocation flows.",
                     "type": "number"
                 },
+                "plan_on_first_org": {
+                    "description": "PlanOnFirstOrg, when set (\"pro\"), grants a paid plan override to the\nuser's first owned org's wallet on creation — admin \"Activate\" with a\npaid (non-Stripe) plan for a user who has no org yet. Consumed alongside\nthe trial intent, then cleared.",
+                    "type": "string"
+                },
                 "project_id": {
                     "description": "When running in Helix Code sandbox",
                     "type": "string"
@@ -37264,6 +37321,10 @@ const docTemplate = `{
                     "description": "If belongs to an organization",
                     "type": "string"
                 },
+                "plan_override": {
+                    "description": "PlanOverride, when set (\"free\"|\"pro\"), forces the quota tier for this\nwallet regardless of the Stripe subscription — used to grant a paid plan\nto a customer who paid out-of-band (bank transfer, no card / no Stripe).\n\"\" means derive the tier from the Stripe subscription as usual. Stripe\nsync only ever writes the Subscription* fields, never this one, so an\nadmin grant can't be reverted by a webhook.",
+                    "type": "string"
+                },
                 "stripe_customer_id": {
                     "type": "string"
                 },

api/pkg/server/organization_handlers.go

@@ -338,6 +338,10 @@ func (apiServer *HelixAPIServer) createOrganization(rw http.ResponseWriter, r *h
 	// without entangling them with trial-state UI or revocation flows.
 	apiServer.consumeUserAdminCredits(ctx, user, createdOrg.ID)
 
+	// Apply any admin-stashed paid-plan grant (PlanOnFirstOrg) as a
+	// PlanOverride on this first org's wallet (out-of-band paid customers).
+	apiServer.consumeUserPlanOnFirstOrg(ctx, user, createdOrg.ID)
+
 	writeResponse(rw, createdOrg, http.StatusCreated)
 }
 

api/pkg/server/server.go

@@ -1344,6 +1344,7 @@ func (apiServer *HelixAPIServer) registerRoutes(ctx context.Context) (*mux.Route
 	adminRouter.HandleFunc("/admin/users/{id}/owned-orgs", system.DefaultWrapper(apiServer.listUserOwnedOrgs)).Methods(http.MethodGet)
 
 	adminRouter.HandleFunc("/admin/orgs", apiServer.adminListOrganizations).Methods(http.MethodGet)
+	adminRouter.HandleFunc("/admin/orgs/{id}/plan", apiServer.adminSetOrgPlan).Methods(http.MethodPost)
 
 	// Sandbox-absorbs-runner pivot: /scheduler/heartbeats and /slots
 	// endpoints removed — no scheduler, no slots.