@nextsparkjs/core 0.1.0-beta.127 → 0.1.0-beta.129

package/dist/templates/app/api/auth/[...all]/route.ts

@@ -7,6 +7,7 @@ import { isPublicSignupRestricted } from "@nextsparkjs/core/lib/teams/helpers";
 // Currently domain validation happens in auth.ts databaseHooks
 import { TeamService } from "@nextsparkjs/core/lib/services";
 import { wrapAuthHandlerWithCors, handleCorsPreflightRequest, addCorsHeaders } from "@nextsparkjs/core/lib/api/helpers";
+import { checkDistributedRateLimit } from "@nextsparkjs/core/lib/api/rate-limit";
 
 const handlers = toNextJsHandler(auth);
 
@@ -45,6 +46,40 @@ export async function GET(req: NextRequest, context: { params: Promise<{ all: st
 
 // Intercept signup requests to validate registration mode
 export async function POST(req: NextRequest) {
+  // Rate limiting: 5 requests per 15 minutes per IP (tier: auth).
+  // Protects login/signup against brute-force and credential stuffing attacks.
+  // IP extraction strategy:
+  // - Cloudflare: cf-connecting-ip (set by Cloudflare, not spoofable behind CF)
+  // - Vercel/trusted proxies: rightmost non-private IP in x-forwarded-for
+  // - Fallback: x-real-ip or 'unknown'
+  const clientIp = (() => {
+    // Cloudflare sets this header and it cannot be spoofed when behind CF
+    const cfIp = req.headers.get('cf-connecting-ip')
+    if (cfIp) return cfIp
+
+    // x-forwarded-for: use rightmost entry (last proxy-appended value is most trustworthy)
+    const forwardedFor = req.headers.get('x-forwarded-for')
+    if (forwardedFor) {
+      const ips = forwardedFor.split(',').map(ip => ip.trim()).filter(Boolean)
+      if (ips.length > 0) return ips[ips.length - 1]
+    }
+
+    return req.headers.get('x-real-ip') || 'unknown'
+  })()
+  const rateLimitResult = await checkDistributedRateLimit(`auth:ip:${clientIp}`, 'auth')
+  if (!rateLimitResult.allowed) {
+    return new NextResponse(JSON.stringify({ error: 'Too many requests' }), {
+      status: 429,
+      headers: {
+        'Content-Type': 'application/json',
+        'Retry-After': '900',
+        'X-RateLimit-Limit': rateLimitResult.limit.toString(),
+        'X-RateLimit-Remaining': '0',
+        'X-RateLimit-Reset': rateLimitResult.resetTime.toString(),
+      },
+    })
+  }
+
   const pathname = req.nextUrl.pathname;
 
   // Determine request type

package/dist/templates/app/api/health/route.ts

@@ -1,31 +1,51 @@
 import { queryWithRLS } from "@nextsparkjs/core/lib/db";
 import { withRateLimitTier } from "@nextsparkjs/core/lib/api/rate-limit";
-import { NextResponse } from "next/server";
+import { isRedisConfigured } from "@nextsparkjs/core/lib/rate-limit-redis";
+import { authenticateRequest } from "@nextsparkjs/core/lib/api/auth/dual-auth";
+import { NextRequest, NextResponse } from "next/server";
+
+export const GET = withRateLimitTier(async (request: NextRequest) => {
+  let dbStatus: 'connected' | 'disconnected' = 'disconnected';
+  let dbError: string | undefined;
 
-export const GET = withRateLimitTier(async () => {
   try {
-    // Test database connection
     await queryWithRLS('SELECT 1');
-    
-    return NextResponse.json({
-      status: 'healthy',
-      timestamp: new Date().toISOString(),
-      services: {
-        database: 'connected',
-        api: 'operational'
-      }
-    });
+    dbStatus = 'connected';
   } catch (error) {
-    console.error('Health check failed:', error);
-    return NextResponse.json({
-      status: 'unhealthy',
-      timestamp: new Date().toISOString(),
-      error: 'Database connection failed',
-      services: {
-        database: 'disconnected',
-        api: 'operational'
-      }
-    }, { status: 503 });
+    dbError = error instanceof Error ? error.message : 'Unknown error';
+    console.error('[health] Database connection failed:', error);
   }
-}, 'read');
 
+  const healthy = dbStatus === 'connected';
+
+  // Public response: only healthy/unhealthy status
+  const publicResponse = {
+    status: healthy ? 'healthy' : 'unhealthy',
+    timestamp: new Date().toISOString(),
+  };
+
+  // Check if caller is authenticated for detailed info
+  const authResult = await authenticateRequest(request);
+  const isAuthenticated = authResult.success && authResult.user;
+
+  if (!isAuthenticated) {
+    return NextResponse.json(publicResponse, { status: healthy ? 200 : 503 });
+  }
+
+  // Authenticated callers get detailed service status
+  const redisConfigured = await isRedisConfigured();
+
+  if (!redisConfigured) {
+    console.error('[health] CRITICAL: Redis not configured — rate limiting is DISABLED. Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN in environment variables.');
+  }
+
+  return NextResponse.json({
+    ...publicResponse,
+    services: {
+      database: dbStatus,
+      rateLimit: redisConfigured ? 'redis' : 'disabled',
+      api: 'operational',
+    },
+    ...(dbError ? { error: dbError } : {}),
+  }, { status: healthy ? 200 : 503 });
+}, 'read');

package/dist/templates/app/api/internal/user-metadata/route.ts

@@ -1,10 +1,16 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { MetaService } from '@nextsparkjs/core/lib/services/meta.service'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 
 // Endpoint interno para crear metadata default después del signup
 export const POST = withRateLimitTier(async (req: NextRequest) => {
   try {
+    const authResult = await authenticateRequest(req)
+    if (!authResult.success || !authResult.user) {
+      return NextResponse.json({ error: 'Authentication required' }, { status: 401 })
+    }
+
     const body = await req.json()
     const { userId, metadata } = body
 
@@ -12,6 +18,10 @@ export const POST = withRateLimitTier(async (req: NextRequest) => {
       return NextResponse.json({ error: 'User ID is required' }, { status: 400 })
     }
 
+    if (userId !== authResult.user.id) {
+      return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+    }
+
     if (!metadata || typeof metadata !== 'object') {
       return NextResponse.json({ error: 'Metadata is required' }, { status: 400 })
     }

package/dist/templates/app/api/superadmin/subscriptions/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { getTypedSession } from '@nextsparkjs/core/lib/auth';
 import { queryWithRLS } from '@nextsparkjs/core/lib/db';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
+import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory';
 
 interface SubscriptionResult {
   id: string;
@@ -23,6 +24,7 @@ interface SubscriptionResult {
   canceledAt: string | null;
   cancelAtPeriodEnd: boolean;
   externalSubscriptionId: string | null;
+  paymentProvider: string | null;
   createdAt: string;
 }
 
@@ -181,6 +183,7 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
         s."canceledAt",
         s."cancelAtPeriodEnd",
         s."externalSubscriptionId",
+        s."paymentProvider",
         s."createdAt"
       FROM "subscriptions" s
       LEFT JOIN "teams" t ON s."teamId" = t.id
@@ -253,6 +256,8 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
       canceledAt: sub.canceledAt,
       cancelAtPeriodEnd: sub.cancelAtPeriodEnd,
       externalSubscriptionId: sub.externalSubscriptionId,
+      paymentProvider: sub.paymentProvider,
+      providerDashboardUrl: getBillingGateway().getSubscriptionDashboardUrl(sub.externalSubscriptionId),
       createdAt: sub.createdAt
     }));
 

package/dist/templates/app/api/superadmin/teams/[teamId]/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { getTypedSession } from '@nextsparkjs/core/lib/auth';
 import { queryWithRLS } from '@nextsparkjs/core/lib/db';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
+import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory';
 
 interface TeamResult {
   id: string;
@@ -37,6 +38,7 @@ interface SubscriptionResult {
   cancelAtPeriodEnd: boolean;
   externalSubscriptionId: string | null;
   externalCustomerId: string | null;
+  paymentProvider: string | null;
   createdAt: string;
 }
 
@@ -144,6 +146,7 @@ export const GET = withRateLimitTier(async (
         s."cancelAtPeriodEnd",
         s."externalSubscriptionId",
         s."externalCustomerId",
+        s."paymentProvider",
         s."createdAt"
       FROM "subscriptions" s
       LEFT JOIN "plans" p ON s."planId" = p.id
@@ -242,6 +245,9 @@ export const GET = withRateLimitTier(async (
         cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
         externalSubscriptionId: subscription.externalSubscriptionId,
         externalCustomerId: subscription.externalCustomerId,
+        paymentProvider: subscription.paymentProvider,
+        providerName: getBillingGateway().getProviderName(),
+        providerDashboardUrl: getBillingGateway().getSubscriptionDashboardUrl(subscription.externalSubscriptionId),
         createdAt: subscription.createdAt
       } : null,
       billingHistory: billingEventsResult.map((event) => ({

package/dist/templates/app/api/v1/billing/cancel/route.ts

@@ -1,7 +1,7 @@
 /**
  * Cancel Subscription Endpoint
  *
- * Allows users to cancel their subscription directly without using Stripe Portal.
+ * Allows users to cancel their subscription directly without going through the billing portal.
  * Supports both soft cancel (at period end) and hard cancel (immediate).
  *
  * P1-4: Cancel subscription directo
@@ -11,11 +11,7 @@ import { NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
 import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
-import {
-  cancelSubscriptionAtPeriodEnd,
-  cancelSubscriptionImmediately,
-  reactivateSubscription
-} from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
@@ -55,7 +51,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
 
   // 3. Permission check using MembershipService
   const membership = await MembershipService.get(authResult.user.id, teamId)
-  const actionResult = membership.canPerformAction('billing.cancel')
+  const actionResult = membership.canPerformAction('team.billing.manage')
 
   if (!actionResult.allowed) {
     return NextResponse.json(
@@ -106,12 +102,13 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     )
   }
 
-  // 6. Cancel via Stripe
+  // 6. Cancel via billing gateway
   try {
+    const gateway = getBillingGateway()
     if (immediate) {
-      await cancelSubscriptionImmediately(subscription.externalSubscriptionId)
+      await gateway.cancelSubscriptionImmediately(subscription.externalSubscriptionId)
     } else {
-      await cancelSubscriptionAtPeriodEnd(subscription.externalSubscriptionId)
+      await gateway.cancelSubscriptionAtPeriodEnd(subscription.externalSubscriptionId)
     }
 
     // 7. Update local DB
@@ -174,7 +171,8 @@ async function handleReactivation(teamId: string) {
   }
 
   try {
-    await reactivateSubscription(subscription.externalSubscriptionId)
+    const gateway = getBillingGateway()
+    await gateway.reactivateSubscription(subscription.externalSubscriptionId)
 
     // Update local DB
     await queryWithRLS(

package/dist/templates/app/api/v1/billing/change-plan/route.ts

@@ -2,7 +2,7 @@
  * Change Plan Endpoint
  *
  * Allows users to upgrade or downgrade their subscription plan.
- * Handles proration via Stripe automatically.
+ * Handles proration via the payment provider automatically.
  *
  * P1-3: Plan Change con Proration
  */
@@ -49,7 +49,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
 
   // 3. Permission check using MembershipService
   const membership = await MembershipService.get(authResult.user.id, teamId)
-  const actionResult = membership.canPerformAction('billing.change-plan')
+  const actionResult = membership.canPerformAction('team.billing.manage')
 
   if (!actionResult.allowed) {
     return NextResponse.json(
@@ -82,7 +82,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
   const { planSlug, billingInterval } = parseResult.data
 
   // 5. Execute plan change
-  const result = await SubscriptionService.changePlan(teamId, planSlug, billingInterval)
+  const result = await SubscriptionService.changePlan(teamId, planSlug, billingInterval, authResult.user.id)
 
   if (!result.success) {
     return NextResponse.json({ success: false, error: result.error }, { status: 400 })

package/dist/templates/app/api/v1/billing/check-action/route.ts

@@ -11,7 +11,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
-import { MembershipService } from '@nextsparkjs/core/lib/services'
+import { SubscriptionService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
@@ -69,11 +69,12 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     )
   }
 
-  // 4. Check action permission using MembershipService
-  // Note: MembershipService.get() does NOT throw for non-members
-  // It returns TeamMembership with role: null
-  const membership = await MembershipService.get(authResult.user.id, teamId)
-  const result = membership.canPerformAction(action)
+  // 4. Check action using SubscriptionService (RBAC + features + quotas)
+  const result = await SubscriptionService.canPerformAction(
+    authResult.user.id,
+    teamId,
+    action
+  )
 
   return NextResponse.json({
     success: true,

package/dist/templates/app/api/v1/billing/checkout/route.ts

@@ -1,17 +1,15 @@
 /**
- * Stripe Checkout Endpoint
+ * Payment Checkout Endpoint
  *
- * Creates a Stripe Checkout session for subscription upgrade.
- * Redirects user to Stripe-hosted checkout page.
+ * Creates a checkout session for subscription upgrade.
+ * Redirects user to the payment provider's hosted checkout page.
  *
  * Security: Requires team owner/admin permission (team.billing.manage)
- *
- * P2: Stripe Integration
  */
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
-import { createCheckoutSession } from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
@@ -71,7 +69,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
 
   // 4. Permission check using MembershipService
   const membership = await MembershipService.get(authResult.user.id, teamId)
-  const actionResult = membership.canPerformAction('billing.checkout')
+  const actionResult = membership.canPerformAction('team.billing.manage')
 
   if (!actionResult.allowed) {
     return NextResponse.json(
@@ -85,17 +83,45 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     )
   }
 
-  // 5. Check existing subscription for customer ID
+  // 5. Check existing subscription
   try {
-    const subscription = await SubscriptionService.getActive(teamId)
+    const subscription = await SubscriptionService.getActive(teamId, authResult.user.id)
+
+    // If already subscribed with an active provider subscription,
+    // use changePlan (immediate proration) instead of creating a new checkout.
+    // This prevents double-billing by updating the existing subscription in Stripe.
+    if (subscription?.externalSubscriptionId) {
+      const result = await SubscriptionService.changePlan(
+        teamId,
+        planSlug,
+        billingPeriod,
+        authResult.user.id
+      )
+
+      if (!result.success) {
+        return NextResponse.json(
+          { success: false, error: result.error },
+          { status: 400 }
+        )
+      }
+
+      // No redirect needed — plan changed immediately via API
+      return NextResponse.json({
+        success: true,
+        data: {
+          changed: true,
+          subscription: result.subscription,
+          warnings: result.downgradeWarnings,
+        }
+      })
+    }
 
-    // Build URLs
+    // No existing provider subscription — create a new checkout session
     const appUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:5173'
     const successUrl = `${appUrl}/dashboard/settings/billing?success=true`
     const cancelUrl = `${appUrl}/dashboard/settings/billing?canceled=true`
 
-    // Create Stripe Checkout session
-    const session = await createCheckoutSession({
+    const session = await getBillingGateway().createCheckoutSession({
       teamId,
       planSlug,
       billingPeriod,
@@ -113,11 +139,11 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
       }
     })
   } catch (error) {
-    console.error('[checkout] Error creating checkout session:', error)
+    console.error('[checkout] Error:', error)
     return NextResponse.json(
       {
         success: false,
-        error: error instanceof Error ? error.message : 'Failed to create checkout session'
+        error: error instanceof Error ? error.message : 'Failed to process checkout'
       },
       { status: 500 }
     )

package/dist/templates/app/api/v1/billing/portal/route.ts

@@ -1,7 +1,7 @@
 /**
- * Stripe Customer Portal Endpoint
+ * Billing Management Portal Endpoint
  *
- * Creates a Stripe Customer Portal session for self-service billing management.
+ * Creates a billing portal session for self-service billing management.
  * Users can update payment methods, view invoices, and cancel subscriptions.
  *
  * P6: Customer Portal
@@ -9,7 +9,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
-import { createPortalSession } from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
@@ -38,7 +38,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
 
   // 3. Permission check using MembershipService
   const membership = await MembershipService.get(authResult.user.id, teamId)
-  const actionResult = membership.canPerformAction('billing.portal')
+  const actionResult = membership.canPerformAction('team.billing.manage')
 
   if (!actionResult.allowed) {
     return NextResponse.json(
@@ -52,7 +52,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     )
   }
 
-  // 4. Get subscription with Stripe customer ID
+  // 4. Get subscription with payment provider customer ID
   try {
     const subscription = await SubscriptionService.getActive(teamId)
 
@@ -69,7 +69,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     const appUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:5173'
     const returnUrl = `${appUrl}/dashboard/settings/billing`
 
-    const session = await createPortalSession({
+    const session = await getBillingGateway().createPortalSession({
       customerId: subscription.externalCustomerId,
       returnUrl
     })

package/dist/templates/app/api/v1/billing/presets.ts

@@ -58,7 +58,7 @@ export default defineApiEndpoint({
     {
       id: 'open-portal',
       title: 'Open Customer Portal',
-      description: 'Get URL for Stripe customer portal',
+      description: 'Get URL for billing management portal',
       method: 'GET',
       tags: ['read', 'portal']
     },

package/dist/templates/app/api/v1/billing/webhooks/polar/route.ts

@@ -20,8 +20,11 @@ import { query, queryOne } from '@nextsparkjs/core/lib/db'
 
 // Polar webhook verification - import from gateway
 import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import type { PolarWebhookExtensions } from '@nextsparkjs/core/lib/billing/polar-webhook'
+import { polarWebhookExtensions } from '@/lib/billing/polar-webhook-extensions'
 
-export async function POST(request: NextRequest) {
+async function handlePolarWebhook(request: NextRequest) {
   // 1. Get raw body and ALL headers (Polar needs full headers for verification)
   const payload = await request.text()
   const headers: Record<string, string> = {}
@@ -83,7 +86,7 @@ export async function POST(request: NextRequest) {
         break
 
       case 'order.paid':
-        await handleOrderPaid(event.data, eventId)
+        await handleOrderPaid(event.data, eventId, polarWebhookExtensions)
         break
 
       default:
@@ -97,6 +100,15 @@ export async function POST(request: NextRequest) {
   }
 }
 
+/**
+ * Rate limiting: 500 requests/hour per IP (tier: webhook).
+ * Polar signature verification is the primary security layer;
+ * rate limiting protects against extreme flood attacks.
+ * NOTE: Rate limiter only reads headers — raw body is NOT consumed here,
+ * so request.text() inside the handler still works correctly.
+ */
+export const POST = withRateLimitTier(handlePolarWebhook, 'webhook')
+
 // ===========================================
 // POLAR EVENT HANDLERS
 // ===========================================
@@ -259,9 +271,15 @@ async function handleSubscriptionCanceled(data: Record<string, unknown>, eventId
 
 /**
  * Handle order.paid
- * Payment was completed for an order (Polar's equivalent of invoice.paid)
+ * Payment was completed for an order (Polar's equivalent of invoice.paid).
+ * - With subscriptionId: recurring subscription payment → mark active, log billing event
+ * - Without subscriptionId: one-time purchase → delegate to extensions.onOneTimePaymentCompleted
  */
-async function handleOrderPaid(data: Record<string, unknown>, eventId: string) {
+async function handleOrderPaid(
+  data: Record<string, unknown>,
+  eventId: string,
+  extensions?: PolarWebhookExtensions
+) {
   const subscriptionId = data.subscriptionId as string | undefined
   const amount = data.amount as number | undefined
   const currency = data.currency as string | undefined
@@ -269,7 +287,7 @@ async function handleOrderPaid(data: Record<string, unknown>, eventId: string) {
   console.log(`[polar-webhook] Order paid: ${eventId}`)
 
   if (subscriptionId) {
-    // Mark subscription as active
+    // Recurring subscription payment — mark active and log
     await query(
       `UPDATE subscriptions
        SET status = 'active',
@@ -278,7 +296,6 @@ async function handleOrderPaid(data: Record<string, unknown>, eventId: string) {
       [subscriptionId]
     )
 
-    // Log billing event for audit trail (recurring payments)
     const sub = await queryOne<{ id: string }>(
       `SELECT id FROM subscriptions WHERE "externalSubscriptionId" = $1 LIMIT 1`,
       [subscriptionId]
@@ -297,6 +314,66 @@ async function handleOrderPaid(data: Record<string, unknown>, eventId: string) {
         ]
       )
     }
+  } else {
+    // One-time purchase — delegate to project-level extension.
+    // Write idempotency record FIRST so Polar retries are deduplicated by the
+    // outer billing_events check, mirroring the subscriptionId branch above.
+    const metadata = (data.metadata as Record<string, string>) ?? {}
+    const teamId = metadata.teamId ?? ''
+    const userId = metadata.userId ?? ''
+
+    const subForIdempotency = teamId
+      ? await queryOne<{ id: string }>(
+          `SELECT id FROM subscriptions WHERE "teamId" = $1 LIMIT 1`,
+          [teamId]
+        )
+      : null
+
+    if (subForIdempotency) {
+      // Check for existing billing event with this polarEventId (idempotency guard).
+      // We use an explicit SELECT instead of ON CONFLICT because billing_events
+      // has no unique constraint on metadata->>'polarEventId'.
+      const existingEvent = await queryOne(
+        `SELECT id FROM "billing_events" WHERE "subscriptionId" = $1 AND metadata->>'polarEventId' = $2`,
+        [subForIdempotency.id, eventId]
+      )
+      if (existingEvent) {
+        console.log(`[polar-webhook] One-time order ${eventId} already processed (idempotency), skipping`)
+        return
+      }
+
+      await query(
+        `INSERT INTO "billing_events" ("subscriptionId", type, status, amount, currency, metadata)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          subForIdempotency.id,
+          'payment',
+          'succeeded',
+          amount ?? 0,
+          currency ?? 'usd',
+          JSON.stringify({ polarEventId: eventId }),
+        ]
+      )
+    } else {
+      console.warn(`[polar-webhook] One-time order ${eventId}: no subscription found for teamId "${teamId}", idempotency record skipped`)
+    }
+
+    if (extensions?.onOneTimePaymentCompleted) {
+      await extensions.onOneTimePaymentCompleted(
+        {
+          id: (data.id as string) ?? eventId,
+          amount: amount ?? 0,
+          currency: currency ?? 'usd',
+          metadata,
+          customerId: data.customerId as string | undefined,
+          externalCustomerId: data.externalCustomerId as string | undefined,
+          productId: data.productId as string | undefined,
+        },
+        { teamId, userId }
+      )
+    } else {
+      console.log(`[polar-webhook] One-time order ${eventId} — no extension handler configured`)
+    }
   }
 }