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

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

@@ -0,0 +1,184 @@
+# Auth API
+
+Authentication endpoints powered by Better Auth with NextSpark extensions.
+
+## Overview
+
+The Auth API provides authentication functionality including sign up, sign in, password reset, and specialized flows like invitation-based registration. Core auth endpoints are handled by Better Auth at `/api/auth/*`, while custom extensions are available at `/api/v1/auth/*`.
+
+## Better Auth Endpoints
+
+These endpoints are handled by Better Auth at `/api/auth/*`:
+
+### Sign Up
+`POST /api/auth/sign-up/email`
+
+Register a new user account.
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "name": "John Doe"
+}
+```
+
+### Sign In
+`POST /api/auth/sign-in/email`
+
+Authenticate with email and password.
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword"
+}
+```
+
+### Sign Out
+`POST /api/auth/sign-out`
+
+End the current session.
+
+### Get Session
+`GET /api/auth/session`
+
+Get current user session.
+
+**Response:**
+```json
+{
+  "user": {
+    "id": "user_123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "emailVerified": true
+  },
+  "session": {
+    "id": "session_abc",
+    "expiresAt": "2024-02-15T10:00:00Z"
+  }
+}
+```
+
+### Forgot Password
+`POST /api/auth/forget-password`
+
+Request password reset email.
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+### Reset Password
+`POST /api/auth/reset-password`
+
+Reset password with token from email.
+
+**Request Body:**
+```json
+{
+  "token": "reset_token_from_email",
+  "newPassword": "newsecurepassword"
+}
+```
+
+---
+
+## NextSpark Extensions
+
+### Sign Up with Invitation
+`POST /api/v1/auth/signup-with-invite`
+
+Create an account and automatically join a team via invitation. This is a single-step flow that:
+1. Validates the invitation token
+2. Creates the user account
+3. Skips email verification (invitation proves ownership)
+4. Adds user to the invited team with specified role
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "firstName": "John",
+  "lastName": "Doe",
+  "inviteToken": "invitation_token_from_email"
+}
+```
+
+**Success Response (201):**
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "user_123",
+      "email": "user@example.com",
+      "firstName": "John",
+      "lastName": "Doe",
+      "emailVerified": true
+    },
+    "teamId": "team_abc123",
+    "redirectTo": "/dashboard/settings/teams"
+  }
+}
+```
+
+**Validation Rules:**
+- Email must match the invitation recipient
+- Password minimum 8 characters
+- Invitation must be pending and not expired
+- Email format validation
+
+---
+
+## Error Responses
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | MISSING_FIELDS | Required fields not provided |
+| 400 | INVALID_EMAIL | Email format is invalid |
+| 400 | INVALID_PASSWORD | Password doesn't meet requirements |
+| 403 | EMAIL_MISMATCH | Email doesn't match invitation |
+| 404 | INVITATION_NOT_FOUND | Invalid invitation token |
+| 409 | USER_ALREADY_EXISTS | Account with email already exists |
+| 409 | INVITATION_NOT_PENDING | Invitation already used or cancelled |
+| 410 | INVITATION_EXPIRED | Invitation has expired |
+| 500 | SIGNUP_FAILED | Account creation failed |
+
+## OAuth Providers
+
+If configured, these OAuth endpoints are available:
+
+- `GET /api/auth/callback/google` - Google OAuth callback
+- `GET /api/auth/callback/github` - GitHub OAuth callback
+- `GET /api/auth/callback/microsoft` - Microsoft OAuth callback
+
+## Session Management
+
+Sessions are managed via secure HTTP-only cookies. Session duration and refresh behavior are configured in the Better Auth settings.
+
+## API Key Authentication
+
+For server-to-server requests, API keys can be used instead of session cookies:
+
+```
+Authorization: Bearer sk_live_xxx
+# or
+x-api-key: sk_live_xxx
+```
+
+See the API Keys documentation for more information.
+
+## Related APIs
+
+- **[API Keys](/api/v1/api-keys)** - Create and manage API keys for server-to-server auth
+- **[Teams](/api/v1/teams)** - Team management and invitation acceptance
+- **[Team Invitations](/api/v1/team-invitations)** - Manage team invitations
+- **[Users](/api/v1/users)** - User profile management after authentication

package/templates/app/api/v1/auth/presets.ts

@@ -0,0 +1,44 @@
+/**
+ * API Presets for Auth
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * Note: Core Better Auth endpoints are at /api/auth/*, not /api/v1/auth/*
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/auth',
+  summary: 'Authentication with Better Auth and NextSpark extensions',
+  presets: [
+    // NextSpark extension: signup with invite
+    {
+      id: 'signup-with-invite',
+      title: 'Sign Up with Invitation',
+      description: 'Create account and join team via invitation token',
+      method: 'POST',
+      path: '/signup-with-invite',
+      payload: {
+        email: 'newuser@example.com',
+        password: 'Test1234',
+        firstName: 'John',
+        lastName: 'Doe',
+        inviteToken: 'invitation_token_here'
+      },
+      tags: ['write', 'signup']
+    },
+    {
+      id: 'signup-with-invite-minimal',
+      title: 'Sign Up (Minimal)',
+      description: 'Sign up with only required fields',
+      method: 'POST',
+      path: '/signup-with-invite',
+      payload: {
+        email: 'user@example.com',
+        password: 'SecurePass123',
+        inviteToken: 'invitation_token_here'
+      },
+      tags: ['write', 'signup']
+    }
+  ]
+})

package/templates/app/api/v1/auth/signup-with-invite/route.ts

@@ -0,0 +1,227 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { auth } from '@nextsparkjs/core/lib/auth'
+import { queryOneWithRLS, mutateWithRLS, getTransactionClient } from '@nextsparkjs/core/lib/db'
+import {
+  createApiResponse,
+  createApiError,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import type { TeamInvitation, TeamMember } from '@nextsparkjs/core/lib/teams/types'
+import { I18N_CONFIG } from '@nextsparkjs/core/lib/config'
+import { withSignupContext } from '@nextsparkjs/core/lib/auth-context'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+interface SignupWithInviteBody {
+  email: string
+  password: string
+  firstName?: string
+  lastName?: string
+  inviteToken: string
+}
+
+// POST /api/v1/auth/signup-with-invite - Create account and auto-accept invitation
+export const POST = withApiLogging(
+  async (req: NextRequest): Promise<NextResponse> => {
+    try {
+      const body: SignupWithInviteBody = await req.json()
+      const { email, password, firstName, lastName, inviteToken } = body
+
+      // Validate required fields
+      if (!email || !password || !inviteToken) {
+        const response = createApiError(
+          'Email, password, and invitation token are required',
+          400,
+          null,
+          'MISSING_FIELDS'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Validate email format
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+      if (!emailRegex.test(email)) {
+        const response = createApiError('Invalid email format', 400, null, 'INVALID_EMAIL')
+        return addCorsHeaders(response)
+      }
+
+      // Validate password length (min 8 characters as per Better Auth config)
+      if (password.length < 8) {
+        const response = createApiError(
+          'Password must be at least 8 characters',
+          400,
+          null,
+          'INVALID_PASSWORD'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Step 1: Validate invitation token (without RLS since user doesn't exist yet)
+      const invitation = await queryOneWithRLS<TeamInvitation>(
+        'SELECT * FROM "team_invitations" WHERE token = $1',
+        [inviteToken],
+        'system' // Use system context for initial validation
+      )
+
+      if (!invitation) {
+        const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
+        return addCorsHeaders(response)
+      }
+
+      // Verify invitation is for the correct email
+      if (invitation.email.toLowerCase() !== email.toLowerCase()) {
+        const response = createApiError(
+          'This invitation was sent to a different email address',
+          403,
+          null,
+          'EMAIL_MISMATCH'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Check if invitation is pending
+      if (invitation.status !== 'pending') {
+        const response = createApiError(
+          `Invitation has already been ${invitation.status}`,
+          409,
+          null,
+          'INVITATION_NOT_PENDING'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Check if invitation has expired
+      const expiresAt = new Date(invitation.expiresAt)
+      if (expiresAt < new Date()) {
+        const response = createApiError('Invitation has expired', 410, null, 'INVITATION_EXPIRED')
+        return addCorsHeaders(response)
+      }
+
+      // Step 2: Create user using Better Auth's internal API
+      // Wrap in signup context to skip automatic team creation
+      // (user will be added to the invited team instead)
+      const signUpRequest = new Request(`${process.env.NEXT_PUBLIC_APP_URL}/api/auth/sign-up/email`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email,
+          password,
+          name: firstName && lastName ? `${firstName} ${lastName}` : firstName || '',
+          firstName,
+          lastName,
+          language: I18N_CONFIG.defaultLocale,
+        }),
+      })
+
+      // Use signup context to signal that we should skip team creation
+      // The user will be added to the invited team instead
+      const signUpResponse = await withSignupContext(
+        { skipTeamCreation: true, invitedTeamId: invitation.teamId },
+        () => auth.handler(signUpRequest)
+      ) as Response
+
+      if (!signUpResponse.ok) {
+        const errorData = await signUpResponse.json() as { message?: string; code?: string }
+
+        // Check if user already exists
+        if (errorData.message?.includes('already exists') || errorData.code === 'USER_ALREADY_EXISTS') {
+          const response = createApiError(
+            'An account with this email already exists. Please sign in instead.',
+            409,
+            null,
+            'USER_ALREADY_EXISTS'
+          )
+          return addCorsHeaders(response)
+        }
+
+        const response = createApiError(
+          errorData.message || 'Failed to create account',
+          signUpResponse.status,
+          null,
+          'SIGNUP_FAILED'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Parse response to get user data
+      const signUpData = await signUpResponse.json()
+      const userId = signUpData.user?.id
+
+      if (!userId) {
+        const response = createApiError(
+          'Failed to create account - no user ID returned',
+          500,
+          null,
+          'SIGNUP_FAILED'
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Step 3: Mark email as verified (skip email verification since invitation proves email ownership)
+      await mutateWithRLS(
+        'UPDATE "users" SET "emailVerified" = true, "updatedAt" = CURRENT_TIMESTAMP WHERE id = $1',
+        [userId],
+        userId
+      )
+
+      // Step 4: Accept the invitation (add user to team)
+      const tx = await getTransactionClient(userId)
+
+      try {
+        // Add user as team member
+        const [member] = await tx.query<TeamMember>(
+          `INSERT INTO "team_members" ("teamId", "userId", role, "invitedBy", "joinedAt")
+           VALUES ($1, $2, $3, $4, NOW())
+           RETURNING *`,
+          [invitation.teamId, userId, invitation.role, invitation.invitedBy]
+        )
+
+        if (!member) {
+          throw new Error('Failed to create team member')
+        }
+
+        // Update invitation status
+        await tx.query(
+          `UPDATE "team_invitations"
+           SET status = 'accepted', "acceptedAt" = NOW(), "updatedAt" = CURRENT_TIMESTAMP
+           WHERE id = $1`,
+          [invitation.id]
+        )
+
+        await tx.commit()
+
+        // Step 5: Return success with user info and redirect URL
+        const response = createApiResponse(
+          {
+            user: {
+              id: userId,
+              email,
+              firstName,
+              lastName,
+              emailVerified: true,
+            },
+            teamId: invitation.teamId,
+            redirectTo: '/dashboard/settings/teams',
+          },
+          { created: true },
+          201
+        )
+        return addCorsHeaders(response)
+      } catch (error) {
+        await tx.rollback()
+        throw error
+      }
+    } catch (error) {
+      console.error('Error in signup-with-invite:', error)
+      const response = createApiError('Internal server error', 500)
+      return addCorsHeaders(response)
+    }
+  }
+)

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

@@ -0,0 +1,206 @@
+/**
+ * Cancel Subscription Endpoint
+ *
+ * Allows users to cancel their subscription directly without using Stripe Portal.
+ * Supports both soft cancel (at period end) and hard cancel (immediate).
+ *
+ * P1-4: Cancel subscription directo
+ */
+
+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'
+import {
+  cancelSubscriptionAtPeriodEnd,
+  cancelSubscriptionImmediately,
+  reactivateSubscription
+} from '@nextsparkjs/core/lib/billing/gateways/stripe'
+import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+
+const cancelSchema = z.object({
+  immediate: z.boolean().optional().default(false),
+  reason: z.string().optional()
+})
+
+/**
+ * POST /api/v1/billing/cancel
+ * Cancel the team's active subscription
+ *
+ * Body:
+ * - immediate: boolean (default: false) - If true, cancels immediately. If false, cancels at period end.
+ * - reason: string (optional) - Reason for cancellation (stored in metadata)
+ */
+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.cancel')
+
+  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 }
+    )
+  }
+
+  // Check if this is a reactivation request
+  if (body.action === 'reactivate') {
+    return handleReactivation(teamId)
+  }
+
+  // Otherwise, it's a cancel request
+  const parseResult = cancelSchema.safeParse(body)
+  if (!parseResult.success) {
+    return Response.json(
+      { success: false, error: 'Invalid request body', details: parseResult.error.issues },
+      { status: 400 }
+    )
+  }
+
+  const { immediate, reason } = parseResult.data
+
+  // 5. Get active subscription
+  const subscription = await SubscriptionService.getActive(teamId)
+
+  if (!subscription || !subscription.externalSubscriptionId) {
+    return Response.json(
+      { success: false, error: 'No active subscription found' },
+      { status: 404 }
+    )
+  }
+
+  // 6. Cancel via Stripe
+  try {
+    if (immediate) {
+      await cancelSubscriptionImmediately(subscription.externalSubscriptionId)
+    } else {
+      await cancelSubscriptionAtPeriodEnd(subscription.externalSubscriptionId)
+    }
+
+    // 7. Update local DB
+    await queryWithRLS(
+      `UPDATE subscriptions
+       SET "cancelAtPeriodEnd" = $1,
+           "canceledAt" = $2,
+           metadata = jsonb_set(COALESCE(metadata, '{}'::jsonb), '{cancelReason}', $3::jsonb),
+           "updatedAt" = now()
+       WHERE id = $4`,
+      [
+        !immediate, // cancelAtPeriodEnd is true for soft cancel
+        immediate ? new Date() : null,
+        JSON.stringify(reason || 'User requested'),
+        subscription.id
+      ]
+    )
+
+    return Response.json({
+      success: true,
+      data: {
+        canceledAt: immediate ? new Date().toISOString() : null,
+        cancelAtPeriodEnd: !immediate,
+        periodEnd: subscription.currentPeriodEnd?.toISOString() || null,
+        message: immediate
+          ? 'Subscription canceled immediately'
+          : 'Subscription will cancel at the end of the current billing period'
+      }
+    })
+  } catch (error) {
+    console.error('[cancel] Error canceling subscription:', error)
+    return Response.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to cancel subscription'
+      },
+      { status: 500 }
+    )
+  }
+}
+
+/**
+ * Handle reactivation of a subscription that was scheduled to cancel
+ */
+async function handleReactivation(teamId: string) {
+  const subscription = await SubscriptionService.getActive(teamId)
+
+  if (!subscription || !subscription.externalSubscriptionId) {
+    return Response.json(
+      { success: false, error: 'No active subscription found' },
+      { status: 404 }
+    )
+  }
+
+  if (!subscription.cancelAtPeriodEnd) {
+    return Response.json(
+      { success: false, error: 'Subscription is not scheduled for cancellation' },
+      { status: 400 }
+    )
+  }
+
+  try {
+    await reactivateSubscription(subscription.externalSubscriptionId)
+
+    // Update local DB
+    await queryWithRLS(
+      `UPDATE subscriptions
+       SET "cancelAtPeriodEnd" = false,
+           "canceledAt" = NULL,
+           metadata = metadata - 'cancelReason',
+           "updatedAt" = now()
+       WHERE id = $1`,
+      [subscription.id]
+    )
+
+    return Response.json({
+      success: true,
+      data: {
+        reactivated: true,
+        message: 'Subscription reactivated successfully'
+      }
+    })
+  } catch (error) {
+    console.error('[cancel] Error reactivating subscription:', error)
+    return Response.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to reactivate subscription'
+      },
+      { status: 500 }
+    )
+  }
+}