@nextsparkjs/core 0.1.0-beta.126 → 0.1.0-beta.128

package/dist/migrations/001_better_auth_and_functions.sql

@@ -41,17 +41,11 @@ BEGIN
 END;
 $$;
 
--- Alias sin schema si lo usás en policies legadas
-CREATE OR REPLACE FUNCTION get_auth_user_id()
-RETURNS TEXT
-LANGUAGE plpgsql
-SECURITY DEFINER
-SET search_path = public
-AS $$
-BEGIN
-  RETURN public.get_auth_user_id();
-END;
-$$;
+-- NOTE: Previously there was an alias function `get_auth_user_id()` (without schema)
+-- that called `public.get_auth_user_id()`. This was removed because PostgreSQL's
+-- `CREATE OR REPLACE` with `SET search_path = public` would overwrite the real
+-- function with the alias, causing infinite recursion. All RLS policies should
+-- use `public.get_auth_user_id()` with the explicit schema qualifier.
 
 -- Utilidad: updatedAt (si no existe ya en otra migration)
 CREATE OR REPLACE FUNCTION public.set_updated_at()

package/dist/migrations/008_team_members_table.sql

@@ -43,6 +43,24 @@ CREATE TRIGGER team_members_set_updated_at
 BEFORE UPDATE ON public."team_members"
 FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
 
+-- ============================================
+-- HELPER FUNCTION (bypasses RLS via SECURITY DEFINER)
+-- ============================================
+
+-- Returns team IDs for a given user, bypassing RLS to prevent self-referencing
+-- recursion. Without this, team_members RLS policies query team_members itself,
+-- causing infinite recursion when any other table (subscriptions, billing_events,
+-- usage) references team_members in its own RLS policy chain.
+CREATE OR REPLACE FUNCTION public.get_user_team_ids(p_user_id TEXT)
+RETURNS SETOF TEXT
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT "teamId" FROM public."team_members" WHERE "userId" = p_user_id;
+$$;
+
 -- ============================================
 -- TEAM MEMBERS ROW LEVEL SECURITY (RLS)
 -- ============================================
@@ -50,23 +68,21 @@ FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
 ALTER TABLE public."team_members" ENABLE ROW LEVEL SECURITY;
 
 -- Team members: visible to members of the same team
+-- Uses get_user_team_ids() (SECURITY DEFINER) to avoid self-referencing recursion
 CREATE POLICY "team_members_select_policy" ON public."team_members"
   FOR SELECT TO authenticated
   USING (
-    "teamId" IN (
-      SELECT "teamId" FROM public."team_members"
-      WHERE "userId" = public.get_auth_user_id()
-    )
+    "teamId" IN (SELECT public.get_user_team_ids(public.get_auth_user_id()))
   );
 
 -- Team members: owners and admins can add members
 CREATE POLICY "team_members_insert_policy" ON public."team_members"
   FOR INSERT TO authenticated
   WITH CHECK (
-    "teamId" IN (
-      SELECT "teamId" FROM public."team_members"
-      WHERE "userId" = public.get_auth_user_id()
-      AND role IN ('owner', 'admin')
+    "teamId" IN (SELECT public.get_user_team_ids(public.get_auth_user_id()))
+    AND EXISTS (
+      SELECT 1 FROM public.get_user_team_ids(public.get_auth_user_id()) AS t
+      WHERE t = "team_members"."teamId"
     )
   );
 
@@ -74,29 +90,17 @@ CREATE POLICY "team_members_insert_policy" ON public."team_members"
 CREATE POLICY "team_members_update_policy" ON public."team_members"
   FOR UPDATE TO authenticated
   USING (
-    "teamId" IN (
-      SELECT "teamId" FROM public."team_members"
-      WHERE "userId" = public.get_auth_user_id()
-      AND role IN ('owner', 'admin')
-    )
+    "teamId" IN (SELECT public.get_user_team_ids(public.get_auth_user_id()))
   )
   WITH CHECK (
-    "teamId" IN (
-      SELECT "teamId" FROM public."team_members"
-      WHERE "userId" = public.get_auth_user_id()
-      AND role IN ('owner', 'admin')
-    )
+    "teamId" IN (SELECT public.get_user_team_ids(public.get_auth_user_id()))
   );
 
 -- Team members: owners and admins can remove members (except themselves)
 CREATE POLICY "team_members_delete_policy" ON public."team_members"
   FOR DELETE TO authenticated
   USING (
-    "teamId" IN (
-      SELECT "teamId" FROM public."team_members"
-      WHERE "userId" = public.get_auth_user_id()
-      AND role IN ('owner', 'admin')
-    )
+    "teamId" IN (SELECT public.get_user_team_ids(public.get_auth_user_id()))
     -- Cannot remove yourself
     AND "userId" != public.get_auth_user_id()
   );

package/dist/styles/classes.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-03-17T22:09:43.971Z",
+  "generated": "2026-03-21T22:28:39.842Z",
   "totalClasses": 1074,
   "classes": [
     "!text-2xl",

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'
 
@@ -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
  */
@@ -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/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'
@@ -94,8 +92,8 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     const successUrl = `${appUrl}/dashboard/settings/billing?success=true`
     const cancelUrl = `${appUrl}/dashboard/settings/billing?canceled=true`
 
-    // Create Stripe Checkout session
-    const session = await createCheckoutSession({
+    // Create checkout session via billing gateway
+    const session = await getBillingGateway().createCheckoutSession({
       teamId,
       planSlug,
       billingPeriod,

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'
 
@@ -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`)
+    }
   }
 }