kybernus 2.2.1 → 2.4.0

package/templates/nodejs-express/mvc/src/services/stripe.service.ts.hbs

@@ -2,21 +2,39 @@ import Stripe from 'stripe';
 import { prisma } from '../config/database';
 
 const stripe = new Stripe(process.env.STRIPE_SECRET_KEY || '', {
-    apiVersion: '2024-12-18.acacia',
+    apiVersion: '2026-02-25.clover',
 });
 
 export interface CreateCheckoutSessionParams {
+    userId: string;
     priceId: string;
-    customerId?: string;
     successUrl: string;
     cancelUrl: string;
 }
 
 export class StripeService {
     /**
-     * Create a checkout session for subscription
+     * Create or retrieve a Stripe customer for the user, then create a checkout session.
      */
     async createCheckoutSession(params: CreateCheckoutSessionParams) {
+        const user = await prisma.user.findUnique({ where: { id: params.userId } });
+        if (!user) throw new Error('User not found');
+
+        let customerId = user.stripeCustomerId;
+
+        if (!customerId) {
+            const customer = await stripe.customers.create({
+                email: user.email,
+                name: user.name ?? undefined,
+                metadata: { userId: user.id },
+            });
+            customerId = customer.id;
+            await prisma.user.update({
+                where: { id: params.userId },
+                data: { stripeCustomerId: customerId },
+            });
+        }
+
         const session = await stripe.checkout.sessions.create({
             mode: 'subscription',
             payment_method_types: ['card'],
@@ -26,20 +44,24 @@ export class StripeService {
                     quantity: 1,
                 },
             ],
-            customer: params.customerId,
+            customer: customerId,
             success_url: params.successUrl,
             cancel_url: params.cancelUrl,
+            client_reference_id: params.userId,
         });
 
         return session;
     }
 
     /**
-     * Create a customer portal session
+     * Create a Stripe customer portal session so the user can manage their subscription.
      */
-    async createPortalSession(customerId: string, returnUrl: string) {
+    async createPortalSession(userId: string, returnUrl: string) {
+        const user = await prisma.user.findUnique({ where: { id: userId } });
+        if (!user?.stripeCustomerId) throw new Error('Stripe customer not found for this user');
+
         const session = await stripe.billingPortal.sessions.create({
-            customer: customerId,
+            customer: user.stripeCustomerId,
             return_url: returnUrl,
         });
 
@@ -47,66 +69,61 @@ export class StripeService {
     }
 
     /**
-     * Handle webhook event
+     * Validate the Stripe webhook signature and handle events.
      */
     async handleWebhook(rawBody: Buffer, signature: string) {
         const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET || '';
 
-        const event = stripe.webhooks.constructEvent(
-            rawBody,
-            signature,
-            webhookSecret
-        );
+        let event: Stripe.Event;
+        try {
+            event = stripe.webhooks.constructEvent(rawBody, signature, webhookSecret);
+        } catch (err: any) {
+            throw new Error(`Webhook signature verification failed: ${err.message}`);
+        }
 
         switch (event.type) {
-            case 'checkout.session.completed':
-                {
-                    const session = event.data.object as Stripe.Checkout.Session;
-                    // Handle successful subscription
-                    console.log('Checkout completed:', session.id);
-                    // Match to user and update DB, e.g., using session.client_reference_id
+            case 'checkout.session.completed': {
+                const session = event.data.object as Stripe.Checkout.Session;
+                const userId = session.client_reference_id;
+                if (userId && session.customer) {
+                    await prisma.user.update({
+                        where: { id: userId },
+                        data: {
+                            stripeCustomerId: session.customer as string,
+                        },
+                    });
                 }
+                console.log('Checkout completed for user:', userId);
                 break;
+            }
 
-            case 'customer.subscription.updated':
-                {
-                     const subscription = event.data.object as Stripe.Subscription;
-                     // Handle subscription update in DB
-                     console.log('Subscription updated:', subscription.id);
-                }
+            case 'customer.subscription.updated': {
+                const subscription = event.data.object as Stripe.Subscription;
+                console.log('Subscription updated:', subscription.id, '| Status:', subscription.status);
+                // TODO: Update subscription status in DB (add subscriptionStatus field to User model)
                 break;
+            }
 
-            case 'customer.subscription.deleted':
-                {
-                     const deletedSubscription = event.data.object as Stripe.Subscription;
-                     // Handle subscription cancellation in DB
-                     console.log('Subscription deleted:', deletedSubscription.id);
-                }
+            case 'customer.subscription.deleted': {
+                const subscription = event.data.object as Stripe.Subscription;
+                console.log('Subscription deleted:', subscription.id);
+                // TODO: Mark user as unsubscribed in DB
                 break;
+            }
 
-            case 'invoice.payment_failed':
-                {
-                     const invoice = event.data.object as Stripe.Invoice;
-                     // Handle failed payment
-                     console.log('Payment failed:', invoice.id);
-                }
+            case 'invoice.payment_failed': {
+                const invoice = event.data.object as Stripe.Invoice;
+                console.log('Payment failed for invoice:', invoice.id);
+                // TODO: Notify user via email
                 break;
+            }
+
+            default:
+                console.log('Unhandled Stripe event:', event.type);
         }
 
         return { received: true };
     }
-
-    /**
-     * Create a Stripe customer
-     */
-    async createCustomer(email: string, name?: string) {
-        const customer = await stripe.customers.create({
-            email,
-            name,
-        });
-
-        return customer;
-    }
 }
 
 export const stripeService = new StripeService();

package/templates/python-fastapi/clean/app/application/services/payment_service.py.hbs

@@ -0,0 +1,85 @@
+import os
+from app.domain.repositories.user_repository import UserRepository
+from app.infrastructure.stripe_provider import StripeProvider
+
+
+class PaymentService:
+    def __init__(self, user_repository: UserRepository, stripe_provider: StripeProvider):
+        self.user_repository = user_repository
+        self.stripe_provider = stripe_provider
+
+    async def create_checkout_session(self, user_id: str, price_id: str) -> str:
+        """Return Stripe Checkout URL for the given user and price."""
+        user = await self.user_repository.find_by_id(user_id)
+        if not user:
+            raise ValueError("User not found")
+
+        customer_id = user.stripe_customer_id
+
+        if not customer_id:
+            customer = self.stripe_provider.create_customer(
+                email=user.email,
+                name=getattr(user, "name", None),
+                user_id=str(user.id),
+            )
+            customer_id = customer.id
+            user.stripe_customer_id = customer_id
+            await self.user_repository.save(user)
+
+        session = self.stripe_provider.create_checkout_session(
+            customer_id=customer_id,
+            price_id=price_id,
+            user_id=str(user_id),
+            success_url=f"{os.getenv('FRONTEND_URL')}/success?session_id={{CHECKOUT_SESSION_ID}}",
+            cancel_url=f"{os.getenv('FRONTEND_URL')}/cancel",
+        )
+        return session.url
+
+    async def create_portal_session(self, user_id: str) -> str:
+        """Return Stripe Portal URL for the given user."""
+        user = await self.user_repository.find_by_id(user_id)
+        if not user or not user.stripe_customer_id:
+            raise ValueError("No Stripe customer found for this user")
+
+        session = self.stripe_provider.create_portal_session(
+            customer_id=user.stripe_customer_id,
+            return_url=f"{os.getenv('FRONTEND_URL')}/dashboard",
+        )
+        return session.url
+
+    async def handle_webhook(self, payload: bytes, sig_header: str) -> dict:
+        """Validate and process a Stripe webhook event."""
+        try:
+            event = self.stripe_provider.construct_event(payload, sig_header)
+        except Exception as e:
+            raise ValueError(f"Webhook signature verification failed: {e}")
+
+        event_type = event["type"]
+        data_object = event["data"]["object"]
+
+        if event_type == "checkout.session.completed":
+            user_id = data_object.get("client_reference_id")
+            customer_id = data_object.get("customer")
+            if user_id and customer_id:
+                user = await self.user_repository.find_by_id(user_id)
+                if user:
+                    user.stripe_customer_id = customer_id
+                    await self.user_repository.save(user)
+            print(f"Checkout completed for user: {user_id}")
+
+        elif event_type == "customer.subscription.updated":
+            print(f"Subscription updated: {data_object.get('id')} | Status: {data_object.get('status')}")
+            # TODO: Update subscriptionStatus field on user
+
+        elif event_type == "customer.subscription.deleted":
+            print(f"Subscription deleted: {data_object.get('id')}")
+            # TODO: Mark user as unsubscribed
+
+        elif event_type == "invoice.payment_failed":
+            print(f"Payment failed for invoice: {data_object.get('id')}")
+            # TODO: Notify user via email
+
+        else:
+            print(f"Unhandled Stripe event: {event_type}")
+
+        return {"received": True}

package/templates/python-fastapi/clean/app/infrastructure/http/payment_controller.py.hbs

@@ -0,0 +1,64 @@
+from fastapi import APIRouter, HTTPException, Header, Request, Depends
+from pydantic import BaseModel
+from app.application.services.payment_service import PaymentService
+from app.infrastructure.database.session import AsyncSessionLocal
+from app.infrastructure.database.user_repository import SQLAlchemyUserRepository
+from app.infrastructure.stripe_provider import StripeProvider
+from app.infrastructure.security.jwt import get_current_user_id
+
+router = APIRouter()
+
+
+def get_payment_service() -> PaymentService:
+    repo = SQLAlchemyUserRepository(AsyncSessionLocal())
+    provider = StripeProvider()
+    return PaymentService(user_repository=repo, stripe_provider=provider)
+
+
+class CheckoutRequest(BaseModel):
+    price_id: str
+
+
+@router.post("/checkout")
+async def create_checkout(
+    data: CheckoutRequest,
+    user_id: str = Depends(get_current_user_id),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Create a Stripe Checkout Session (authenticated)."""
+    try:
+        url = await service.create_checkout_session(user_id=user_id, price_id=data.price_id)
+        return {"url": url}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/portal")
+async def create_portal(
+    user_id: str = Depends(get_current_user_id),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Open Stripe Billing Portal (authenticated)."""
+    try:
+        url = await service.create_portal_session(user_id=user_id)
+        return {"url": url}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/webhook")
+async def stripe_webhook(
+    request: Request,
+    stripe_signature: str = Header(None, alias="stripe-signature"),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Handle Stripe webhook events. No auth required – raw body."""
+    if not stripe_signature:
+        raise HTTPException(status_code=400, detail="Missing stripe-signature header")
+
+    payload = await request.body()
+    try:
+        result = await service.handle_webhook(payload=payload, sig_header=stripe_signature)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

package/templates/python-fastapi/clean/app/infrastructure/stripe_provider.py.hbs

@@ -0,0 +1,44 @@
+import stripe
+import os
+
+stripe.api_key = os.getenv("STRIPE_SECRET_KEY")
+stripe.api_version = "2026-02-25.clover"
+
+
+class StripeProvider:
+    """Infrastructure provider that wraps the Stripe SDK."""
+
+    def create_customer(self, email: str, name: str | None = None, user_id: str | None = None):
+        return stripe.Customer.create(
+            email=email,
+            name=name,
+            metadata={"userId": user_id} if user_id else {},
+        )
+
+    def create_checkout_session(
+        self,
+        customer_id: str,
+        price_id: str,
+        user_id: str,
+        success_url: str,
+        cancel_url: str,
+    ):
+        return stripe.checkout.Session.create(
+            mode="subscription",
+            payment_method_types=["card"],
+            line_items=[{"price": price_id, "quantity": 1}],
+            customer=customer_id,
+            success_url=success_url,
+            cancel_url=cancel_url,
+            client_reference_id=str(user_id),
+        )
+
+    def create_portal_session(self, customer_id: str, return_url: str):
+        return stripe.billing_portal.Session.create(
+            customer=customer_id,
+            return_url=return_url,
+        )
+
+    def construct_event(self, payload: bytes, sig_header: str):
+        webhook_secret = os.getenv("STRIPE_WEBHOOK_SECRET", "")
+        return stripe.Webhook.construct_event(payload, sig_header, webhook_secret)

package/templates/python-fastapi/clean/app/main.py.hbs

@@ -1,11 +1,12 @@
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
-from app.infrastructure.http import auth_controller
+from app.infrastructure.http import auth_controller, payment_controller
 from app.config import get_settings
 from app.infrastructure.database.session import engine, Base
 
 settings = get_settings()
 
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     # Create tables on startup (for development)
@@ -13,20 +14,22 @@ async def lifespan(app: FastAPI):
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
     yield
-    # Cleanup
     await engine.dispose()
 
+
 app = FastAPI(
     title="{{projectName}} - Clean Architecture",
-    lifespan=lifespan
+    lifespan=lifespan,
 )
 
 app.include_router(auth_controller.router, prefix=settings.API_V1_STR + "/auth", tags=["Auth"])
+app.include_router(payment_controller.router, prefix=settings.API_V1_STR + "/payments", tags=["Payments"])
+
 
 @app.get("/health")
 def health():
     return {
-        "status": "ok", 
+        "status": "ok",
         "architecture": "clean",
-        "project": settings.PROJECT_NAME
+        "project": settings.PROJECT_NAME,
     }

package/templates/python-fastapi/hexagonal/app/adapters/inbound/payment_http_adapter.py.hbs

@@ -0,0 +1,64 @@
+from fastapi import APIRouter, HTTPException, Header, Request, Depends
+from pydantic import BaseModel
+from app.core.payment_service import PaymentService
+from app.adapters.outbound.stripe_adapter import StripeAdapter
+from app.infrastructure.database.session import AsyncSessionLocal
+from app.infrastructure.database.user_repository import SQLAlchemyUserRepository
+from app.infrastructure.security.jwt import get_current_user_id
+
+router = APIRouter()
+
+
+def get_payment_service() -> PaymentService:
+    repo = SQLAlchemyUserRepository(AsyncSessionLocal())
+    adapter = StripeAdapter()
+    return PaymentService(user_repository=repo, stripe_adapter=adapter)
+
+
+class CheckoutRequest(BaseModel):
+    price_id: str
+
+
+@router.post("/checkout")
+async def create_checkout(
+    data: CheckoutRequest,
+    user_id: str = Depends(get_current_user_id),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Create a Stripe Checkout Session (authenticated)."""
+    try:
+        url = await service.create_checkout_session(user_id=user_id, price_id=data.price_id)
+        return {"url": url}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/portal")
+async def create_portal(
+    user_id: str = Depends(get_current_user_id),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Open Stripe Billing Portal (authenticated)."""
+    try:
+        url = await service.create_portal_session(user_id=user_id)
+        return {"url": url}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/webhook")
+async def stripe_webhook(
+    request: Request,
+    stripe_signature: str = Header(None, alias="stripe-signature"),
+    service: PaymentService = Depends(get_payment_service),
+):
+    """Handle Stripe webhook events. No auth required – raw body."""
+    if not stripe_signature:
+        raise HTTPException(status_code=400, detail="Missing stripe-signature header")
+
+    payload = await request.body()
+    try:
+        result = await service.handle_webhook(payload=payload, sig_header=stripe_signature)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))

package/templates/python-fastapi/hexagonal/app/adapters/outbound/stripe_adapter.py.hbs

@@ -0,0 +1,44 @@
+import stripe
+import os
+
+stripe.api_key = os.getenv("STRIPE_SECRET_KEY")
+stripe.api_version = "2026-02-25.clover"
+
+
+class StripeAdapter:
+    """Outbound adapter: wraps the Stripe SDK for use by the core domain."""
+
+    def create_customer(self, email: str, name: str | None = None, user_id: str | None = None):
+        return stripe.Customer.create(
+            email=email,
+            name=name,
+            metadata={"userId": user_id} if user_id else {},
+        )
+
+    def create_checkout_session(
+        self,
+        customer_id: str,
+        price_id: str,
+        user_id: str,
+        success_url: str,
+        cancel_url: str,
+    ):
+        return stripe.checkout.Session.create(
+            mode="subscription",
+            payment_method_types=["card"],
+            line_items=[{"price": price_id, "quantity": 1}],
+            customer=customer_id,
+            success_url=success_url,
+            cancel_url=cancel_url,
+            client_reference_id=str(user_id),
+        )
+
+    def create_portal_session(self, customer_id: str, return_url: str):
+        return stripe.billing_portal.Session.create(
+            customer=customer_id,
+            return_url=return_url,
+        )
+
+    def construct_event(self, payload: bytes, sig_header: str):
+        webhook_secret = os.getenv("STRIPE_WEBHOOK_SECRET", "")
+        return stripe.Webhook.construct_event(payload, sig_header, webhook_secret)

package/templates/python-fastapi/hexagonal/app/core/payment_service.py.hbs

@@ -0,0 +1,81 @@
+import os
+from app.core.ports.user_repository import UserRepository
+from app.adapters.outbound.stripe_adapter import StripeAdapter
+
+
+class PaymentService:
+    """Core domain service for payment operations (Hexagonal Architecture)."""
+
+    def __init__(self, user_repository: UserRepository, stripe_adapter: StripeAdapter):
+        self.user_repository = user_repository
+        self.stripe_adapter = stripe_adapter
+
+    async def create_checkout_session(self, user_id: str, price_id: str) -> str:
+        user = await self.user_repository.find_by_id(user_id)
+        if not user:
+            raise ValueError("User not found")
+
+        customer_id = user.stripe_customer_id
+
+        if not customer_id:
+            customer = self.stripe_adapter.create_customer(
+                email=user.email,
+                name=getattr(user, "name", None),
+                user_id=str(user.id),
+            )
+            customer_id = customer.id
+            user.stripe_customer_id = customer_id
+            await self.user_repository.save(user)
+
+        session = self.stripe_adapter.create_checkout_session(
+            customer_id=customer_id,
+            price_id=price_id,
+            user_id=str(user_id),
+            success_url=f"{os.getenv('FRONTEND_URL')}/success?session_id={{CHECKOUT_SESSION_ID}}",
+            cancel_url=f"{os.getenv('FRONTEND_URL')}/cancel",
+        )
+        return session.url
+
+    async def create_portal_session(self, user_id: str) -> str:
+        user = await self.user_repository.find_by_id(user_id)
+        if not user or not user.stripe_customer_id:
+            raise ValueError("No Stripe customer found for this user")
+
+        session = self.stripe_adapter.create_portal_session(
+            customer_id=user.stripe_customer_id,
+            return_url=f"{os.getenv('FRONTEND_URL')}/dashboard",
+        )
+        return session.url
+
+    async def handle_webhook(self, payload: bytes, sig_header: str) -> dict:
+        try:
+            event = self.stripe_adapter.construct_event(payload, sig_header)
+        except Exception as e:
+            raise ValueError(f"Webhook signature verification failed: {e}")
+
+        event_type = event["type"]
+        data_object = event["data"]["object"]
+
+        if event_type == "checkout.session.completed":
+            user_id = data_object.get("client_reference_id")
+            customer_id = data_object.get("customer")
+            if user_id and customer_id:
+                user = await self.user_repository.find_by_id(user_id)
+                if user:
+                    user.stripe_customer_id = customer_id
+                    await self.user_repository.save(user)
+            print(f"Checkout completed for user: {user_id}")
+
+        elif event_type == "customer.subscription.updated":
+            print(f"Subscription updated: {data_object.get('id')} | Status: {data_object.get('status')}")
+
+        elif event_type == "customer.subscription.deleted":
+            print(f"Subscription deleted: {data_object.get('id')}")
+
+        elif event_type == "invoice.payment_failed":
+            print(f"Payment failed for invoice: {data_object.get('id')}")
+
+        else:
+            print(f"Unhandled Stripe event: {event_type}")
+
+        return {"received": True}

package/templates/python-fastapi/hexagonal/app/main.py.hbs

@@ -1,30 +1,36 @@
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from app.adapters.inbound.http_adapter import router as auth_router
+from app.adapters.inbound.payment_http_adapter import router as payment_router
 from app.infrastructure.database.session import engine, Base
 from app.config import get_settings
 
 settings = get_settings()
 
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     # Create tables on startup (for development)
+    # In production, use Alembic migrations
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
     yield
     await engine.dispose()
 
+
 app = FastAPI(
     title="{{projectName}} - Hexagonal Architecture",
-    lifespan=lifespan
+    lifespan=lifespan,
 )
 
 app.include_router(auth_router, prefix=settings.API_V1_STR + "/auth", tags=["Auth"])
+app.include_router(payment_router, prefix=settings.API_V1_STR + "/payments", tags=["Payments"])
+
 
 @app.get("/health")
 def health():
     return {
-        "status": "ok", 
+        "status": "ok",
         "architecture": "hexagonal",
-        "project": settings.PROJECT_NAME
+        "project": settings.PROJECT_NAME,
     }