@nextsparkjs/core 0.1.0-beta.83 → 0.1.0-beta.85

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

@@ -0,0 +1,97 @@
+/**
+ * Change Plan Endpoint
+ *
+ * Allows users to upgrade or downgrade their subscription plan.
+ * Handles proration via Stripe automatically.
+ *
+ * P1-3: Plan Change con Proration
+ */
+
+import { NextRequest } 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'
+
+const changePlanSchema = z.object({
+  planSlug: z.string().min(1, 'Plan slug is required'),
+  billingInterval: z.enum(['monthly', 'yearly']).default('monthly'),
+})
+
+/**
+ * POST /api/v1/billing/change-plan
+ * Change the team's subscription plan (upgrade or downgrade)
+ *
+ * Body:
+ * - planSlug: string - Target plan slug
+ * - billingInterval: 'monthly' | 'yearly' (default: monthly)
+ */
+export async function POST(request: NextRequest) {
+  // 1. Dual authentication
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success || !authResult.user) {
+    return createAuthError('Unauthorized', 401)
+  }
+
+  // 2. Get team context
+  const teamId = request.headers.get('x-team-id') || authResult.user.defaultTeamId
+
+  if (!teamId) {
+    return Response.json(
+      {
+        success: false,
+        error: 'No team context available. Please provide x-team-id header.',
+      },
+      { status: 400 }
+    )
+  }
+
+  // 3. Permission check using MembershipService
+  const membership = await MembershipService.get(authResult.user.id, teamId)
+  const actionResult = membership.canPerformAction('billing.change-plan')
+
+  if (!actionResult.allowed) {
+    return Response.json(
+      {
+        success: false,
+        error: actionResult.message,
+        reason: actionResult.reason,
+        meta: actionResult.meta,
+      },
+      { status: 403 }
+    )
+  }
+
+  // 4. Parse and validate request body
+  let body: Record<string, unknown>
+  try {
+    body = await request.json()
+  } catch {
+    return Response.json({ success: false, error: 'Invalid JSON body' }, { status: 400 })
+  }
+
+  const parseResult = changePlanSchema.safeParse(body)
+  if (!parseResult.success) {
+    return Response.json(
+      { success: false, error: 'Invalid request body', details: parseResult.error.issues },
+      { status: 400 }
+    )
+  }
+
+  const { planSlug, billingInterval } = parseResult.data
+
+  // 5. Execute plan change
+  const result = await SubscriptionService.changePlan(teamId, planSlug, billingInterval)
+
+  if (!result.success) {
+    return Response.json({ success: false, error: result.error }, { status: 400 })
+  }
+
+  return Response.json({
+    success: true,
+    data: {
+      subscription: result.subscription,
+      warnings: result.downgradeWarnings,
+    },
+  })
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Check Action Endpoint
+ *
+ * Verifies if a user can perform a specific action by checking:
+ * 1. RBAC permissions (role-based access control)
+ * 2. Plan features (subscription-based access)
+ * 3. Quota limits (usage-based access)
+ *
+ * FIX1: This endpoint was missing, causing useMembership.canDo() to fail
+ */
+
+import { NextRequest } from 'next/server'
+import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { MembershipService } from '@nextsparkjs/core/lib/services'
+import { z } from 'zod'
+
+const checkActionSchema = z.object({
+  action: z.string().min(1, 'Action is required'),
+  teamId: z.string().uuid().optional()
+})
+
+export async function POST(request: NextRequest) {
+  // 1. Dual authentication (API Key OR Session)
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success || !authResult.user) {
+    return createAuthError('Unauthorized', 401)
+  }
+
+  // 2. Parse and validate request body
+  let body
+  try {
+    body = await request.json()
+  } catch {
+    return Response.json(
+      { success: false, error: 'Invalid JSON body' },
+      { status: 400 }
+    )
+  }
+
+  const parseResult = checkActionSchema.safeParse(body)
+  if (!parseResult.success) {
+    return Response.json(
+      {
+        success: false,
+        error: 'Validation failed',
+        details: parseResult.error.issues
+      },
+      { status: 400 }
+    )
+  }
+
+  const { action, teamId: bodyTeamId } = parseResult.data
+
+  // 3. Get team context (from body, header, or user's default)
+  const teamId =
+    bodyTeamId ||
+    request.headers.get('x-team-id') ||
+    authResult.user.defaultTeamId
+
+  if (!teamId) {
+    return Response.json(
+      {
+        success: false,
+        error: 'No team context available. Please provide teamId in body or x-team-id header.'
+      },
+      { status: 400 }
+    )
+  }
+
+  // 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)
+
+  return Response.json({
+    success: true,
+    data: result
+  })
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Stripe Checkout Endpoint
+ *
+ * Creates a Stripe Checkout session for subscription upgrade.
+ * Redirects user to Stripe-hosted checkout page.
+ *
+ * Security: Requires team owner/admin permission (team.billing.manage)
+ *
+ * P2: Stripe Integration
+ */
+
+import { NextRequest } from 'next/server'
+import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createCheckoutSession } from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
+import { z } from 'zod'
+
+const checkoutSchema = z.object({
+  planSlug: z.string().min(1, 'Plan slug is required'),
+  billingPeriod: z.enum(['monthly', 'yearly']).default('monthly')
+})
+
+export async function POST(request: NextRequest) {
+  // 1. Dual authentication
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success || !authResult.user) {
+    return createAuthError('Unauthorized', 401)
+  }
+
+  // 2. Parse and validate request body
+  let body
+  try {
+    body = await request.json()
+  } catch {
+    return Response.json(
+      { success: false, error: 'Invalid JSON body' },
+      { status: 400 }
+    )
+  }
+
+  const parseResult = checkoutSchema.safeParse(body)
+  if (!parseResult.success) {
+    return Response.json(
+      {
+        success: false,
+        error: 'Validation failed',
+        details: parseResult.error.issues
+      },
+      { status: 400 }
+    )
+  }
+
+  const { planSlug, billingPeriod } = parseResult.data
+
+  // 3. Get team context
+  const teamId =
+    request.headers.get('x-team-id') ||
+    authResult.user.defaultTeamId
+
+  if (!teamId) {
+    return Response.json(
+      {
+        success: false,
+        error: 'No team context available. Please provide x-team-id header.'
+      },
+      { status: 400 }
+    )
+  }
+
+  // 4. Permission check using MembershipService
+  const membership = await MembershipService.get(authResult.user.id, teamId)
+  const actionResult = membership.canPerformAction('billing.checkout')
+
+  if (!actionResult.allowed) {
+    return Response.json(
+      {
+        success: false,
+        error: actionResult.message,
+        reason: actionResult.reason,
+        meta: actionResult.meta,
+      },
+      { status: 403 }
+    )
+  }
+
+  // 5. Check existing subscription for customer ID
+  try {
+    const subscription = await SubscriptionService.getActive(teamId)
+
+    // Build URLs
+    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({
+      teamId,
+      planSlug,
+      billingPeriod,
+      successUrl,
+      cancelUrl,
+      customerEmail: authResult.user.email,
+      customerId: subscription?.externalCustomerId || undefined
+    })
+
+    return Response.json({
+      success: true,
+      data: {
+        url: session.url,
+        sessionId: session.id
+      }
+    })
+  } catch (error) {
+    console.error('[checkout] Error creating checkout session:', error)
+    return Response.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to create checkout session'
+      },
+      { status: 500 }
+    )
+  }
+}

package/templates/app/api/v1/billing/docs.md

@@ -0,0 +1,209 @@
+# Billing API
+
+Manage subscriptions, plans, and billing operations for teams.
+
+## Overview
+
+The Billing API integrates with Stripe to handle subscription management, checkout sessions, plan changes, and customer portal access. All billing operations are scoped to teams.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+The `x-team-id` header or user's default team is used for team context.
+
+## Endpoints
+
+### List Plans
+`GET /api/v1/billing/plans`
+
+Returns available subscription plans. Public plans visible to all, hidden plans only to superadmin.
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "plan_123",
+      "slug": "pro",
+      "name": "Pro Plan",
+      "description": "For growing teams",
+      "priceMonthly": 29,
+      "priceYearly": 290,
+      "currency": "USD",
+      "features": ["unlimited_projects", "api_access"],
+      "limits": {
+        "team_members": 10,
+        "storage_gb": 100
+      }
+    }
+  ]
+}
+```
+
+### Create Checkout Session
+`POST /api/v1/billing/checkout`
+
+Creates a Stripe Checkout session for subscription upgrade. Returns a URL to redirect the user.
+
+**Required Permission:** `billing.checkout` (team owner/admin)
+
+**Request Body:**
+```json
+{
+  "planSlug": "pro",
+  "billingPeriod": "monthly"
+}
+```
+
+**Parameters:**
+- `planSlug` (string, required): The plan to subscribe to
+- `billingPeriod` (string): "monthly" or "yearly" (default: "monthly")
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "url": "https://checkout.stripe.com/...",
+    "sessionId": "cs_live_..."
+  }
+}
+```
+
+### Open Customer Portal
+`GET /api/v1/billing/portal`
+
+Creates a Stripe Customer Portal session for managing payment methods and viewing invoices.
+
+**Required Permission:** `billing.portal` (team owner/admin)
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "url": "https://billing.stripe.com/..."
+  }
+}
+```
+
+### Change Plan
+`POST /api/v1/billing/change-plan`
+
+Change the current subscription to a different plan.
+
+**Required Permission:** `billing.change_plan` (team owner/admin)
+
+**Request Body:**
+```json
+{
+  "planSlug": "enterprise",
+  "billingPeriod": "yearly"
+}
+```
+
+### Cancel Subscription
+`POST /api/v1/billing/cancel`
+
+Cancel the current subscription. Cancellation takes effect at the end of the billing period.
+
+**Required Permission:** `billing.cancel` (team owner/admin)
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "canceledAt": "2024-02-01T00:00:00Z",
+    "effectiveDate": "2024-02-28T23:59:59Z"
+  }
+}
+```
+
+### Check Action Permission
+`POST /api/v1/billing/check-action`
+
+Verify if the current user can perform a specific action based on RBAC, plan features, and quotas.
+
+**Request Body:**
+```json
+{
+  "action": "team.invite_member",
+  "teamId": "team_123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "allowed": true,
+    "reason": null
+  }
+}
+```
+
+Or if not allowed:
+```json
+{
+  "success": true,
+  "data": {
+    "allowed": false,
+    "reason": "quota_exceeded",
+    "message": "Team member limit reached",
+    "meta": {
+      "limit": 5,
+      "current": 5
+    }
+  }
+}
+```
+
+### Stripe Webhook
+`POST /api/v1/billing/webhooks/stripe`
+
+Handles Stripe webhook events for subscription lifecycle management.
+
+**Note:** This endpoint is called by Stripe, not by your application. It requires Stripe signature verification.
+
+**Handled Events:**
+- `checkout.session.completed` - New subscription created
+- `customer.subscription.updated` - Plan changed
+- `customer.subscription.deleted` - Subscription canceled
+- `invoice.paid` - Payment successful
+- `invoice.payment_failed` - Payment failed
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters or missing required fields |
+| 401 | Unauthorized - Authentication required |
+| 403 | Forbidden - Insufficient permissions or plan doesn't allow action |
+| 404 | Not Found - Plan or subscription not found |
+| 500 | Server Error - Stripe API error or internal error |
+
+## Billing Period Proration
+
+When changing plans mid-cycle:
+- **Upgrade:** Prorated charge for the difference
+- **Downgrade:** Credit applied to next invoice
+- **Same price:** No proration
+
+## Test Mode
+
+In development, Stripe test mode is used. Test card numbers:
+- Success: `4242 4242 4242 4242`
+- Decline: `4000 0000 0000 0002`
+- 3D Secure: `4000 0025 0000 3155`
+
+## Related APIs
+
+- **[Teams](/api/v1/teams)** - Team subscription and usage endpoints
+- **[Teams Subscription](/api/v1/teams/{teamId}/subscription)** - View team's current subscription
+- **[Teams Usage](/api/v1/teams/{teamId}/usage/{limit})** - Check quota usage
+- **[Teams Invoices](/api/v1/teams/{teamId}/invoices)** - View billing invoices

package/templates/app/api/v1/billing/plans/route.ts

@@ -0,0 +1,85 @@
+/**
+ * Plans API - Billing system
+ *
+ * GET /api/v1/billing/plans - List all plans (public can see public plans)
+ * POST /api/v1/billing/plans - Create a plan (superadmin only)
+ */
+
+import { NextRequest } from 'next/server'
+import { validateAndAuthenticateRequest, createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { PlanService } from '@nextsparkjs/core/lib/services'
+import { createPlanSchema } from '@nextsparkjs/core/lib/billing/schema'
+import { mutateWithRLS } from '@nextsparkjs/core/lib/db'
+
+export async function GET(request: NextRequest) {
+  // Plans list is partially public (public plans visible to all, hidden plans only to superadmin)
+  let includeHidden = false
+
+  try {
+    const { auth } = await validateAndAuthenticateRequest(request)
+    // Check if user is superadmin (for full access including hidden plans)
+    includeHidden = auth.scopes.includes('*') || auth.scopes.includes('superadmin:all')
+  } catch {
+    // Not authenticated, only show public plans
+    includeHidden = false
+  }
+
+  try {
+    const plans = await PlanService.list({ includeHidden })
+    return createApiResponse(plans)
+  } catch (error) {
+    console.error('[Billing API] Error fetching plans:', error)
+    return createApiError('Failed to fetch plans', 500)
+  }
+}
+
+export async function POST(request: NextRequest) {
+  // Authenticate request
+  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  if (rateLimitResponse) return rateLimitResponse
+
+  // Check superadmin permission
+  if (!auth.scopes.includes('*') && !auth.scopes.includes('superadmin:all')) {
+    return createApiError('Only superadmin can create plans', 403)
+  }
+
+  try {
+    const body = await request.json()
+    const data = createPlanSchema.parse(body)
+
+    const { rows } = await mutateWithRLS(
+      `
+      INSERT INTO plans (
+        slug, name, description, type, visibility,
+        "priceMonthly", "priceYearly", currency, "trialDays",
+        features, limits, metadata, "sortOrder"
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+      RETURNING *
+    `,
+      [
+        data.slug,
+        data.name,
+        data.description,
+        data.type,
+        data.visibility,
+        data.priceMonthly,
+        data.priceYearly,
+        data.currency,
+        data.trialDays,
+        JSON.stringify(data.features),
+        JSON.stringify(data.limits),
+        JSON.stringify(data.metadata),
+        data.sortOrder,
+      ]
+    )
+
+    return createApiResponse(rows[0], { created: true }, 201)
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : ''
+    if (errorMessage.includes('duplicate') || errorMessage.includes('unique')) {
+      return createApiError('Plan slug already exists', 400)
+    }
+    console.error('[Billing API] Error creating plan:', error)
+    return createApiError('Failed to create plan', 500)
+  }
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Stripe Customer Portal Endpoint
+ *
+ * Creates a Stripe Customer Portal session for self-service billing management.
+ * Users can update payment methods, view invoices, and cancel subscriptions.
+ *
+ * P6: Customer Portal
+ */
+
+import { NextRequest } from 'next/server'
+import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createPortalSession } from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
+
+export async function POST(request: NextRequest) {
+  // 1. Dual authentication
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success || !authResult.user) {
+    return createAuthError('Unauthorized', 401)
+  }
+
+  // 2. Get team context
+  const teamId =
+    request.headers.get('x-team-id') ||
+    authResult.user.defaultTeamId
+
+  if (!teamId) {
+    return Response.json(
+      {
+        success: false,
+        error: 'No team context available. Please provide x-team-id header.'
+      },
+      { status: 400 }
+    )
+  }
+
+  // 3. Permission check using MembershipService
+  const membership = await MembershipService.get(authResult.user.id, teamId)
+  const actionResult = membership.canPerformAction('billing.portal')
+
+  if (!actionResult.allowed) {
+    return Response.json(
+      {
+        success: false,
+        error: actionResult.message,
+        reason: actionResult.reason,
+        meta: actionResult.meta,
+      },
+      { status: 403 }
+    )
+  }
+
+  // 4. Get subscription with Stripe customer ID
+  try {
+    const subscription = await SubscriptionService.getActive(teamId)
+
+    if (!subscription?.externalCustomerId) {
+      return Response.json(
+        {
+          success: false,
+          error: 'No billing account found. Please upgrade to a paid plan first.'
+        },
+        { status: 400 }
+      )
+    }
+
+    const appUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:5173'
+    const returnUrl = `${appUrl}/dashboard/settings/billing`
+
+    const session = await createPortalSession({
+      customerId: subscription.externalCustomerId,
+      returnUrl
+    })
+
+    return Response.json({
+      success: true,
+      data: { url: session.url }
+    })
+  } catch (error) {
+    console.error('[portal] Error creating portal session:', error)
+    return Response.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to create portal session'
+      },
+      { status: 500 }
+    )
+  }
+}