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

package/templates/app/api/v1/team-invitations/[token]/accept/route.ts

@@ -0,0 +1,179 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { queryOneWithRLS, mutateWithRLS, getTransactionClient } from '@nextsparkjs/core/lib/db'
+import {
+  createApiResponse,
+  createApiError,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { checkRateLimit } from '@nextsparkjs/core/lib/api/rate-limit'
+import { RATE_LIMITS } from '@nextsparkjs/core/lib/api/keys'
+import type { TeamInvitation, TeamMember } from '@nextsparkjs/core/lib/teams/types'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+// POST /api/v1/team-invitations/:token/accept - Accept invitation and become member
+export const POST = withApiLogging(
+  async (req: NextRequest, { params }: { params: Promise<{ token: string }> }): Promise<NextResponse> => {
+    try {
+      // Authenticate using dual auth
+      const authResult = await authenticateRequest(req)
+
+      if (!authResult.success) {
+        return NextResponse.json(
+          { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
+          { status: 401 }
+        )
+      }
+
+      if (authResult.rateLimitResponse) {
+        return authResult.rateLimitResponse as NextResponse
+      }
+
+      // Apply specific rate limit for invitation responses (50 req/min)
+      const rateLimitConfig = RATE_LIMITS['teams:invite:respond']
+      const rateLimitKey = `invite:respond:${authResult.user!.id}`
+      const rateLimit = checkRateLimit(rateLimitKey, rateLimitConfig.requests, rateLimitConfig.windowMs)
+
+      if (!rateLimit.allowed) {
+        const response = createApiError(
+          'Rate limit exceeded. Please try again later.',
+          429,
+          { retryAfter: Math.ceil((rateLimit.resetTime - Date.now()) / 1000) },
+          'RATE_LIMIT_EXCEEDED'
+        )
+        return addCorsHeaders(response)
+      }
+
+      const { token } = await params
+
+      // Validate that token is not empty
+      if (!token || token.trim() === '') {
+        const response = createApiError('Invitation token is required', 400, null, 'MISSING_TOKEN')
+        return addCorsHeaders(response)
+      }
+
+      // Get invitation by token
+      const invitation = await queryOneWithRLS<TeamInvitation>(
+        'SELECT * FROM "team_invitations" WHERE token = $1',
+        [token],
+        authResult.user!.id
+      )
+
+      if (!invitation) {
+        const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
+        return addCorsHeaders(response)
+      }
+
+      // Verify invitation is for the current user's email
+      if (invitation.email.toLowerCase() !== authResult.user!.email.toLowerCase()) {
+        const response = createApiError(
+          'This invitation is for 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()) {
+        // Mark as expired
+        await mutateWithRLS(
+          'UPDATE "team_invitations" SET status = \'expired\', "updatedAt" = CURRENT_TIMESTAMP WHERE id = $1',
+          [invitation.id],
+          authResult.user!.id
+        )
+
+        const response = createApiError('Invitation has expired', 410, null, 'INVITATION_EXPIRED')
+        return addCorsHeaders(response)
+      }
+
+      // Check if user is already a member
+      const existingMember = await queryOneWithRLS<TeamMember>(
+        'SELECT * FROM "team_members" WHERE "teamId" = $1 AND "userId" = $2',
+        [invitation.teamId, authResult.user!.id],
+        authResult.user!.id
+      )
+
+      if (existingMember) {
+        const response = createApiError('You are already a member of this team', 409, null, 'ALREADY_MEMBER')
+        return addCorsHeaders(response)
+      }
+
+      // Use transaction to ensure atomicity
+      const tx = await getTransactionClient(authResult.user!.id)
+
+      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, authResult.user!.id, 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()
+
+        // Fetch member with user details
+        const memberWithUser = await queryOneWithRLS<
+          TeamMember & {
+            userName: string | null
+            userEmail: string
+            userImage: string | null
+          }
+        >(
+          `SELECT
+            tm.*,
+            u.name as "userName",
+            u.email as "userEmail",
+            u.image as "userImage"
+          FROM "team_members" tm
+          INNER JOIN "users" u ON tm."userId" = u.id
+          WHERE tm.id = $1`,
+          [member.id],
+          authResult.user!.id
+        )
+
+        const response = createApiResponse(memberWithUser, { created: true }, 201)
+        return addCorsHeaders(response)
+      } catch (error) {
+        await tx.rollback()
+        throw error
+      }
+    } catch (error) {
+      console.error('Error accepting invitation:', error)
+      const response = createApiError('Internal server error', 500)
+      return addCorsHeaders(response)
+    }
+  }
+)

package/templates/app/api/v1/team-invitations/[token]/decline/route.ts

@@ -0,0 +1,120 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { queryOneWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db'
+import {
+  createApiResponse,
+  createApiError,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { checkRateLimit } from '@nextsparkjs/core/lib/api/rate-limit'
+import { RATE_LIMITS } from '@nextsparkjs/core/lib/api/keys'
+import type { TeamInvitation } from '@nextsparkjs/core/lib/teams/types'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+// POST /api/v1/team-invitations/:token/decline - Decline invitation
+export const POST = withApiLogging(
+  async (req: NextRequest, { params }: { params: Promise<{ token: string }> }): Promise<NextResponse> => {
+    try {
+      // Authenticate using dual auth
+      const authResult = await authenticateRequest(req)
+
+      if (!authResult.success) {
+        return NextResponse.json(
+          { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
+          { status: 401 }
+        )
+      }
+
+      if (authResult.rateLimitResponse) {
+        return authResult.rateLimitResponse as NextResponse
+      }
+
+      // Apply specific rate limit for invitation responses (50 req/min)
+      const rateLimitConfig = RATE_LIMITS['teams:invite:respond']
+      const rateLimitKey = `invite:respond:${authResult.user!.id}`
+      const rateLimit = checkRateLimit(rateLimitKey, rateLimitConfig.requests, rateLimitConfig.windowMs)
+
+      if (!rateLimit.allowed) {
+        const response = createApiError(
+          'Rate limit exceeded. Please try again later.',
+          429,
+          { retryAfter: Math.ceil((rateLimit.resetTime - Date.now()) / 1000) },
+          'RATE_LIMIT_EXCEEDED'
+        )
+        return addCorsHeaders(response)
+      }
+
+      const { token } = await params
+
+      // Validate that token is not empty
+      if (!token || token.trim() === '') {
+        const response = createApiError('Invitation token is required', 400, null, 'MISSING_TOKEN')
+        return addCorsHeaders(response)
+      }
+
+      // Get invitation by token
+      const invitation = await queryOneWithRLS<TeamInvitation>(
+        'SELECT * FROM "team_invitations" WHERE token = $1',
+        [token],
+        authResult.user!.id
+      )
+
+      if (!invitation) {
+        const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
+        return addCorsHeaders(response)
+      }
+
+      // Verify invitation is for the current user's email
+      if (invitation.email.toLowerCase() !== authResult.user!.email.toLowerCase()) {
+        const response = createApiError(
+          'This invitation is for 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)
+      }
+
+      // Update invitation status to declined
+      const result = await mutateWithRLS(
+        `UPDATE "team_invitations"
+         SET status = 'declined', "declinedAt" = NOW(), "updatedAt" = CURRENT_TIMESTAMP
+         WHERE id = $1
+         RETURNING *`,
+        [invitation.id],
+        authResult.user!.id
+      )
+
+      if (result.rows.length === 0) {
+        const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
+        return addCorsHeaders(response)
+      }
+
+      const declinedInvitation = result.rows[0]
+
+      const response = createApiResponse(declinedInvitation)
+      return addCorsHeaders(response)
+    } catch (error) {
+      console.error('Error declining invitation:', error)
+      const response = createApiError('Internal server error', 500)
+      return addCorsHeaders(response)
+    }
+  }
+)

package/templates/app/api/v1/team-invitations/[token]/route.ts

@@ -0,0 +1,89 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { queryOne } from '@nextsparkjs/core/lib/db'
+import {
+  createApiResponse,
+  createApiError,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import type { TeamInvitation } from '@nextsparkjs/core/lib/teams/types'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+// GET /api/v1/team-invitations/:token - Get invitation details (public endpoint for preview)
+export const GET = withApiLogging(
+  async (req: NextRequest, { params }: { params: Promise<{ token: string }> }): Promise<NextResponse> => {
+    try {
+      const { token } = await params
+
+      // Validate that token is not empty
+      if (!token || token.trim() === '') {
+        const response = createApiError('Invitation token is required', 400, null, 'MISSING_TOKEN')
+        return addCorsHeaders(response)
+      }
+
+      // Get invitation by token with team and inviter details
+      const invitation = await queryOne<
+        TeamInvitation & {
+          teamName: string
+          inviterName: string | null
+          inviterEmail: string
+        }
+      >(
+        `SELECT
+          ti.*,
+          t.name as "teamName",
+          u.name as "inviterName",
+          u.email as "inviterEmail"
+        FROM "team_invitations" ti
+        INNER JOIN "teams" t ON ti."teamId" = t.id
+        INNER JOIN "users" u ON ti."invitedBy" = u.id
+        WHERE ti.token = $1`,
+        [token]
+      )
+
+      if (!invitation) {
+        const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
+        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)
+      }
+
+      // Check if invitation is still pending
+      if (invitation.status !== 'pending') {
+        const response = createApiError(
+          `Invitation has already been ${invitation.status}`,
+          409,
+          null,
+          `INVITATION_${invitation.status.toUpperCase()}`
+        )
+        return addCorsHeaders(response)
+      }
+
+      // Return public invitation details (don't expose sensitive data)
+      const publicDetails = {
+        teamName: invitation.teamName,
+        inviterName: invitation.inviterName || invitation.inviterEmail,
+        role: invitation.role,
+        email: invitation.email,
+        expiresAt: invitation.expiresAt
+      }
+
+      const response = createApiResponse(publicDetails)
+      return addCorsHeaders(response)
+    } catch (error) {
+      console.error('Error fetching invitation:', error)
+      const response = createApiError('Internal server error', 500)
+      return addCorsHeaders(response)
+    }
+  }
+)

package/templates/app/api/v1/team-invitations/docs.md

@@ -0,0 +1,88 @@
+# Team Invitations API
+
+Manage team invitations for adding new members to teams.
+
+## Overview
+
+The Team Invitations API allows you to create, list, and manage pending invitations to join a team. Invitations are sent via email and can be accepted by the recipient.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Invitations
+`GET /api/v1/team-invitations`
+
+Returns all pending invitations for the current team.
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "inv_123",
+      "email": "newuser@example.com",
+      "role": "member",
+      "status": "pending",
+      "expiresAt": "2024-02-15T10:30:00Z",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+### Create Invitation
+`POST /api/v1/team-invitations`
+
+Send a new invitation to join the team.
+
+**Request Body:**
+```json
+{
+  "email": "newuser@example.com",
+  "role": "member"
+}
+```
+
+**Roles:**
+- `member` - Basic team member
+- `admin` - Can manage team settings and members
+- `owner` - Full control (only one per team)
+
+### Cancel Invitation
+`DELETE /api/v1/team-invitations/[id]`
+
+Cancel a pending invitation.
+
+**Path Parameters:**
+- `id` (string, required): Invitation ID
+
+### Resend Invitation
+`POST /api/v1/team-invitations/[id]/resend`
+
+Resend the invitation email.
+
+**Path Parameters:**
+- `id` (string, required): Invitation ID
+
+## Invitation Flow
+
+1. Admin creates invitation with email and role
+2. System sends invitation email with unique link
+3. Recipient clicks link and signs up/signs in
+4. User is automatically added to the team
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Invitation doesn't exist |
+| 409 | Conflict - User already in team or invitation pending |
+| 422 | Validation Error - Invalid email |

package/templates/app/api/v1/team-invitations/presets.ts

@@ -0,0 +1,43 @@
+/**
+ * API Presets for Team Invitations
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/team-invitations',
+  summary: 'Manage team invitations for new members',
+  presets: [
+    {
+      id: 'list-pending',
+      title: 'List Pending Invitations',
+      description: 'Fetch all pending invitations for the team',
+      method: 'GET',
+      tags: ['read', 'list']
+    },
+    {
+      id: 'invite-member',
+      title: 'Invite as Member',
+      description: 'Send invitation with member role',
+      method: 'POST',
+      payload: {
+        email: 'newuser@example.com',
+        role: 'member'
+      },
+      tags: ['write', 'create', 'invite']
+    },
+    {
+      id: 'invite-admin',
+      title: 'Invite as Admin',
+      description: 'Send invitation with admin role',
+      method: 'POST',
+      payload: {
+        email: 'admin@example.com',
+        role: 'admin'
+      },
+      tags: ['write', 'create', 'invite', 'admin']
+    }
+  ]
+})

package/templates/app/api/v1/team-invitations/route.ts

@@ -0,0 +1,114 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import {
+  createApiResponse,
+  createApiError,
+  createPaginationMeta,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { invitationListQuerySchema } from '@nextsparkjs/core/lib/teams/schema'
+import type { TeamInvitation } from '@nextsparkjs/core/lib/teams/types'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+// GET /api/v1/team-invitations - List pending invitations for current user
+export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
+  try {
+    // Authenticate using dual auth
+    const authResult = await authenticateRequest(req)
+
+    if (!authResult.success) {
+      return NextResponse.json(
+        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
+        { status: 401 }
+      )
+    }
+
+    if (authResult.rateLimitResponse) {
+      return authResult.rateLimitResponse as NextResponse
+    }
+
+    // Get user email to find invitations
+    const userEmail = authResult.user!.email
+
+    // Parse query parameters
+    const { searchParams } = new URL(req.url)
+    const queryParams = {
+      page: searchParams.get('page'),
+      limit: searchParams.get('limit'),
+      status: searchParams.get('status'),
+    }
+
+    const validatedQuery = invitationListQuerySchema.parse(queryParams)
+    const { page, limit, status } = validatedQuery
+    const offset = (page - 1) * limit
+
+    // Build WHERE clause based on filters
+    let whereClause = 'WHERE ti.email = $1'
+    const queryValues: unknown[] = [userEmail]
+    let paramCount = 2
+
+    if (status) {
+      whereClause += ` AND ti.status = $${paramCount}`
+      queryValues.push(status)
+      paramCount++
+    } else {
+      // Default to pending invitations only
+      whereClause += ` AND ti.status = $${paramCount}`
+      queryValues.push('pending')
+      paramCount++
+    }
+
+    // Add pagination params
+    queryValues.push(limit, offset)
+
+    const invitations = await queryWithRLS<
+      TeamInvitation & {
+        teamName: string
+        teamSlug: string
+        inviterName: string | null
+        inviterEmail: string
+      }
+    >(
+      `SELECT
+        ti.*,
+        t.name as "teamName",
+        t.slug as "teamSlug",
+        u.name as "inviterName",
+        u.email as "inviterEmail"
+      FROM "team_invitations" ti
+      INNER JOIN "teams" t ON ti."teamId" = t.id
+      INNER JOIN "users" u ON ti."invitedBy" = u.id
+      ${whereClause}
+      ORDER BY ti."createdAt" DESC
+      LIMIT $${paramCount++} OFFSET $${paramCount++}`,
+      queryValues,
+      authResult.user!.id
+    )
+
+    // Get total count for pagination
+    const totalResult = await queryWithRLS<{ count: string }>(
+      `SELECT COUNT(*) as count
+       FROM "team_invitations" ti
+       ${whereClause}`,
+      queryValues.slice(0, -2), // Remove limit and offset
+      authResult.user!.id
+    )
+
+    const total = parseInt(totalResult[0]?.count || '0', 10)
+    const paginationMeta = createPaginationMeta(page, limit, total)
+
+    const response = createApiResponse(invitations, paginationMeta)
+    return addCorsHeaders(response)
+  } catch (error) {
+    console.error('Error fetching invitations:', error)
+    const response = createApiError('Internal server error', 500)
+    return addCorsHeaders(response)
+  }
+})