feat(ui-react): add billing & subscription management

[luizhf42]

What

Adds the full billing and subscription management surface to the React console for Cloud tenants. Cloud users can now subscribe, manage payment methods, access the Stripe Billing Portal, and see billing-status warnings — all from the Settings page.

Why

The React UI had zero billing functionality (Team #71: 0 of 7 billing tasks done). The backend (9 billing endpoints) and design system were already in place; this PR wires the UI to them.

Fixes: shellhub-io/team#71

Changes

• hooks/useBilling.ts: React Query wrappers for all billing mutations and queries (useSubscription, useCustomer, useCreateCustomer, useCreateSubscription, useAttachPaymentMethod, useDetachPaymentMethod, useSetDefaultPaymentMethod). Includes useOpenBillingPortal as a manual axios wrapper for /api/billing/portal, which is not in the OpenAPI spec (registered dynamically in the cloud module).

• types/billing.ts: BillingStatus union literal, typed Customer, Subscription, PaymentMethod, NamespaceBilling with safe narrowing functions. cvc is intentionally absent — the backend always sends the masked sentinel "xxx" and the field is never displayed.

• BillingSection (Settings.tsx): Status badge, per-status warning banners, Subscribe button (shown only for inactive / canceled / incomplete_expired — statuses where no active Stripe subscription exists), and Open Portal button. Includes hash-scroll on mount for the /settings/billing return URL and a pageshow listener to refetch subscription state after navigating back from the Portal.

• BillingDialog: 4-step wizard (Overview → Payment method → Review → Success), lazy-loaded so Stripe never lands in the Settings initial chunk. Step 3 gates success on active or trialing status only — incomplete and other non-terminal states surface specific error messages rather than false positives.

• BillingPayment: Stripe Elements card form with payment-method list (set-default / detach). Bootstraps the Stripe customer on mount with a cancellation-safe sequential flow: refresh namespace → create customer if absent → refresh namespace again.

• BillingWarning: Device-limit dialog for HTTP 402 responses, wired into DeviceActionDialog and ContainerActionDialog. Non-owners see a passive message; owners get a "Go to Billing" shortcut.

• env.ts: Added stripePublishableKey to ClientConfig; fixed a concurrency bug where simultaneous loadConfig() callers could each fire a separate fetch("/config.json").

• App.tsx: Added /settings/billing redirect route so the Stripe Portal return_url (hardcoded to that path in the backend) lands correctly.

• gen-config.sh / docker-compose.yml: Emit SHELLHUB_STRIPE_PUBLISHABLE_KEY into config.json.

Testing

End-to-end requires SHELLHUB_CLOUD=true, SHELLHUB_BILLING=stripe, and valid Stripe keys. Key paths to verify:

• Fresh namespace: Subscribe → auto-create customer → test card 4242 4242 4242 4242 → Confirm → status flips to active.
• Declined cards: 4000 0000 0000 0002 and 4000 0000 0000 9995 should surface mapped error messages.
• 402 path: open unpaid invoice in Stripe → Subscribe → "unpaid invoices" alert with role="alert".
• Portal return: navigate to Portal → browser back → subscription status refetches (verify via React Query Devtools).
• /settings/billing direct navigation → Settings opens with Billing section in view.
• Device-limit 402: accept device over free-plan limit → BillingWarning → "Go to Billing" → /settings#billing.
• Non-owner: billing card shows owner-only notice; no Subscribe or Portal buttons.
• Community / Enterprise (SHELLHUB_CLOUD=false): billing section not rendered.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 3m 8s —— View job

---

Code Review Complete

Reviewed 31 files across code quality, security, testing, TypeScript/React patterns, and architecture. 2 inline issues posted (2 medium).

Additional notes

• Security: No vulnerabilities found. Stripe publishable key handling, noopener,noreferrer on window.open, and permission gating via useHasPermission are all correctly implemented.
• Architecture: Stripe dependencies are properly code-split via React.lazy() and only loaded when getConfig().cloud is true. Interface changes (onBillingWarning prop) are additive and optional — no breaking changes.
• Testing: Good coverage for BillingDialog, BillingSection, BillingWarning, useBilling hooks, and type narrowing functions. BillingPayment.tsx (419 lines, complex bootstrap + Stripe integration) has no direct tests — it's mocked in all test suites. Consider adding tests for the bootstrap flow and error paths.

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[otavio]

/review

[github-actions]

Claude finished @otavio's task in 7m 6s —— View job

---

Code Review Complete

Reviewed 32 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

Summary

• Security: Stripe publishable key handling is correct (public by design). window.open uses noopener,noreferrer. Permission gating via useHasPermission("billing:subscribe") is consistently applied across BillingSection, BillingWarning, and action dialogs. No XSS vectors — all dynamic data rendered as React text nodes.
• Architecture: Stripe dependencies properly code-split via React.lazy(). The onBillingWarning prop on DeviceActionDialog and ContainerActionDialog is additive and optional — no breaking changes. Config changes (gen-config.sh, env.ts, docker-compose.yml) default to empty strings, maintaining backward compatibility with non-Cloud deployments.
• Cross-repo: Billing portal response shape ({url: string}) matches the cloud backend's StripePortal struct. All BillingStatus values align with the cloud backend's SubscriptionStatus constants.
• Testing: Good coverage across BillingDialog, BillingSection, BillingWarning, useBilling hooks, type narrowing functions, and Stripe error mapping. Mock setups correctly satisfy transitive dependencies from React.lazy loading.
• Patterns: Fetch error interceptor enrichment pattern (isSdkError → cast → extract message) correctly extracts server-provided error messages from the response body. The loadConfig() concurrency fix properly deduplicates in-flight fetches.

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 2m 28s —— View job

---

Code Review Complete

Reviewed 32 files across code quality, security, testing, TypeScript/React patterns, and architecture. 1 inline issue posted (1 medium).

Additional notes

• Security: No vulnerabilities found. Stripe publishable key handling, noopener,noreferrer on window.open, and permission gating via useHasPermission are all correctly implemented. No XSS vectors — all dynamic data rendered as React text nodes.
• Architecture: All frontend billing types (BillingStatus, Customer, Subscription, Invoice, PaymentMethod) match the cloud backend contracts. The onBillingWarning prop additions are optional and backward compatible. Config changes default to empty strings, maintaining compatibility with non-Cloud deployments.
• Testing: Good coverage across BillingDialog, BillingSection, BillingWarning, useBilling hooks, type narrowing functions, and Stripe error mapping. BillingPayment.tsx is mocked in all consumer tests (deliberate — deeply coupled to Stripe Elements runtime).
• Cross-repo: Billing portal response shape ({url: string}) matches the cloud backend's StripePortal struct. All 10 BillingStatus values align with the cloud backend's SubscriptionStatus constants.

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[otavio]

/review

[github-actions]

Claude finished @otavio's task in 2m 47s —— View job

---

Code Review Complete

Reviewed 32 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

Summary

• Security: No vulnerabilities found. Stripe publishable key handling is correct (public by design). window.open uses noopener,noreferrer. Permission gating via useHasPermission("billing:subscribe") is consistently applied across BillingSection, BillingWarning, and action dialogs. No XSS vectors — all dynamic data rendered as React text nodes. The fetch error interceptor enrichment pattern (isSdkError → cast → extract message) correctly extracts server-provided error messages from the response body.
• Architecture: All 10 BillingStatus values match the cloud backend's SubscriptionStatus constants exactly. Billing portal response shape ({url: string}) matches the cloud backend's StripePortal struct. The onBillingWarning prop additions are optional and backward compatible. Config changes default to empty strings, maintaining compatibility with non-Cloud deployments.
• Testing: Good coverage across BillingDialog, BillingSection, BillingWarning, useBilling hooks, type narrowing functions, and Stripe error mapping (75 test cases). Mock setups correctly satisfy transitive dependencies from React.lazy loading.
• React patterns: Bootstrap effect cleanup correctly resets bootstrapRef.current = false for StrictMode double-mount compatibility (fixed from prior review). The invalidateRef pattern in BillingSection avoids unnecessary pageshow listener re-registration while remaining functionally correct (queryClient is a stable singleton). Stripe dependencies properly code-split via React.lazy().
• Prior review findings: All 3 issues from previous reviews have been addressed — StrictMode bootstrap fix (aba1810), React Compiler rationale for skipping useCallback, and useRef for invalidate stability (f15b534).

---

If you push additional changes and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 5m 20s —— View job

---

Code Review Complete

Reviewed 32 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

Summary

• Security: No vulnerabilities found. Stripe publishable key handling is correct (public by design). window.open uses noopener,noreferrer. Permission gating via useHasPermission("billing:subscribe") is consistently applied across BillingSection, BillingWarning, and action dialogs. No XSS vectors — all dynamic data rendered as React text nodes.
• Architecture: All 10 BillingStatus values match the cloud backend's SubscriptionStatus constants exactly. Billing portal response shape ({url: string}) matches the cloud backend's StripePortal struct. The onBillingWarning prop additions are optional and backward compatible. Config changes default to empty strings, maintaining compatibility with non-Cloud deployments.
• Testing: Good coverage across BillingDialog, BillingSection, BillingWarning, useBilling hooks, type narrowing functions, and Stripe error mapping (75 test cases). Mocks are correctly structured with mutable { value: ... } objects for per-test configuration.
• React patterns: Bootstrap effect cleanup correctly resets bootstrapRef.current = false for StrictMode double-mount compatibility (fixed in aba1810). The invalidateRef pattern in BillingSection avoids unnecessary pageshow listener re-registration while remaining functionally correct (queryClient is a stable singleton). Stripe dependencies properly code-split via React.lazy(). The 402 handling in DeviceActionDialog and ContainerActionDialog correctly falls through to setError when onBillingWarning is not provided.
• Prior review findings: All 3 issues from previous reviews have been addressed — StrictMode bootstrap fix, React Compiler rationale for skipping useCallback, and useRef for invalidate stability.

---

If you push additional changes and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 2m 51s —— View job

---

Code Review Complete

Reviewed 32 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

Summary

• Security: No vulnerabilities found. Stripe publishable key handling is correct (public by design). window.open uses noopener,noreferrer. Permission gating via useHasPermission("billing:subscribe") is consistently applied across BillingSection, BillingWarning, and action dialogs. No XSS vectors — all dynamic data rendered as React text nodes.
• Architecture: All 10 BillingStatus values match the cloud backend's SubscriptionStatus constants exactly. Billing portal response shape ({url: string}) matches the cloud backend's StripePortal struct. The onBillingWarning prop additions are optional and backward compatible. Config changes default to empty strings, maintaining compatibility with non-Cloud deployments.
• Testing: Good coverage across BillingDialog, BillingSection, BillingWarning, useBilling hooks, type narrowing functions, and Stripe error mapping (75 test cases). BillingPayment.tsx is mocked in consumer tests (deliberate — deeply coupled to Stripe Elements runtime).
• React patterns: Bootstrap effect cleanup correctly resets bootstrapRef.current = false for StrictMode double-mount compatibility (fixed in aba1810). The invalidateRef pattern in BillingSection avoids unnecessary pageshow listener re-registration while remaining functionally correct (queryClient is a stable singleton). Stripe dependencies properly code-split via React.lazy(). The fetch error interceptor enrichment pattern (isSdkError → cast → extract error) correctly extracts server-provided error messages from the response body.
• Prior review findings: All 3 issues from previous reviews have been addressed — StrictMode bootstrap fix, React Compiler rationale for skipping useCallback, and useRef for invalidate stability.

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.