@nextsparkjs/core 0.1.0-beta.7 → 0.1.0-beta.70

package/dist/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/dist/templates/app/api/v1/team-invitations/route.ts

@@ -11,6 +11,7 @@ import {
 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'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 // Handle CORS preflight
 export async function OPTIONS() {
@@ -18,7 +19,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/team-invitations - List pending invitations for current user
-export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
+export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
     // Authenticate using dual auth
     const authResult = await authenticateRequest(req)
@@ -111,4 +112,4 @@ export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse
     const response = createApiError('Internal server error', 500)
     return addCorsHeaders(response)
   }
-})
+}), 'read');

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

@@ -9,6 +9,7 @@ import {
   addCorsHeaders,
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { TeamMemberService, MembershipService } from '@nextsparkjs/core/lib/services'
 import type { TeamInvitation } from '@nextsparkjs/core/lib/teams/types'
 
@@ -18,7 +19,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams/:teamId/invitations - List pending invitations for a team
-export const GET = withApiLogging(
+export const GET = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -98,10 +99,10 @@ export const GET = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'read')
 
 // DELETE /api/v1/teams/:teamId/invitations/:invitationId - Cancel/revoke an invitation
-export const DELETE = withApiLogging(
+export const DELETE = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -168,4 +169,4 @@ export const DELETE = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')

package/dist/templates/app/api/v1/teams/[teamId]/invoices/[invoiceNumber]/route.ts

@@ -8,6 +8,7 @@ import {
   addCorsHeaders,
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { MembershipService } from '@nextsparkjs/core/lib/services'
 import type { InvoiceResponse } from '@nextsparkjs/core/lib/validation/invoices'
 
@@ -17,7 +18,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams/:teamId/invoices/:invoiceNumber - Get single invoice (owner only)
-export const GET = withApiLogging(
+export const GET = withRateLimitTier(withApiLogging(
   async (
     req: NextRequest,
     { params }: { params: Promise<{ teamId: string; invoiceNumber: string }> }
@@ -102,4 +103,4 @@ export const GET = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'read')

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

@@ -9,6 +9,7 @@ import {
   addCorsHeaders,
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { MembershipService } from '@nextsparkjs/core/lib/services'
 import { invoiceQuerySchema } from '@nextsparkjs/core/lib/validation/invoices'
 import type { InvoiceResponse } from '@nextsparkjs/core/lib/validation/invoices'
@@ -19,7 +20,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams/:teamId/invoices - List team invoices (owner only)
-export const GET = withApiLogging(
+export const GET = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth (API key OR session)
@@ -122,4 +123,4 @@ export const GET = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'read')

package/dist/templates/app/api/v1/teams/[teamId]/members/[memberId]/route.ts

@@ -8,6 +8,7 @@ import {
   addCorsHeaders,
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { updateMemberRoleSchema } from '@nextsparkjs/core/lib/teams/schema'
 import { MembershipService } from '@nextsparkjs/core/lib/services'
 import { validateRoleTransition, canManageRole } from '@nextsparkjs/core/lib/teams/permissions'
@@ -19,7 +20,7 @@ export async function OPTIONS() {
 }
 
 // PATCH /api/v1/teams/:teamId/members/:memberId - Update member role
-export const PATCH = withApiLogging(
+export const PATCH = withRateLimitTier(withApiLogging(
   async (
     req: NextRequest,
     { params }: { params: Promise<{ teamId: string; memberId: string }> }
@@ -155,10 +156,10 @@ export const PATCH = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')
 
 // DELETE /api/v1/teams/:teamId/members/:memberId - Remove member from team
-export const DELETE = withApiLogging(
+export const DELETE = withRateLimitTier(withApiLogging(
   async (
     req: NextRequest,
     { params }: { params: Promise<{ teamId: string; memberId: string }> }
@@ -260,4 +261,4 @@ export const DELETE = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')

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

@@ -10,7 +10,7 @@ import {
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { isSuperAdmin } from '@nextsparkjs/core/lib/api/auth/permissions'
-import { checkRateLimit } from '@nextsparkjs/core/lib/api/rate-limit'
+import { checkRateLimit, withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { RATE_LIMITS } from '@nextsparkjs/core/lib/api/keys'
 import { inviteMemberSchema, memberListQuerySchema } from '@nextsparkjs/core/lib/teams/schema'
 import { TeamMemberService, MembershipService } from '@nextsparkjs/core/lib/services'
@@ -37,7 +37,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams/:teamId/members - List team members
-export const GET = withApiLogging(
+export const GET = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -159,10 +159,10 @@ export const GET = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'read')
 
 // POST /api/v1/teams/:teamId/members - Invite new member (creates invitation)
-export const POST = withApiLogging(
+export const POST = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -355,4 +355,4 @@ export const POST = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')

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

@@ -8,6 +8,7 @@ import {
   addCorsHeaders,
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { updateTeamSchema } from '@nextsparkjs/core/lib/teams/schema'
 import { TeamService, MembershipService } from '@nextsparkjs/core/lib/services'
 import type { Team, TeamRole } from '@nextsparkjs/core/lib/teams/types'
@@ -18,7 +19,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams/:teamId - Get team details
-export const GET = withApiLogging(
+export const GET = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -87,10 +88,10 @@ export const GET = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'read')
 
 // PATCH /api/v1/teams/:teamId - Update team (owners/admins only)
-export const PATCH = withApiLogging(
+export const PATCH = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -228,10 +229,10 @@ export const PATCH = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')
 
 // DELETE /api/v1/teams/:teamId - Delete team (owners only, NOT personal teams)
-export const DELETE = withApiLogging(
+export const DELETE = withRateLimitTier(withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ teamId: string }> }): Promise<NextResponse> => {
     try {
       // Authenticate using dual auth
@@ -291,4 +292,4 @@ export const DELETE = withApiLogging(
       return addCorsHeaders(response)
     }
   }
-)
+), 'write')

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

@@ -6,13 +6,14 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { validateAndAuthenticateRequest, createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 
 interface RouteParams {
   params: Promise<{ teamId: string }>
 }
 
-export async function GET(request: NextRequest, props: RouteParams) {
+export const GET = withRateLimitTier(async function GET(request: NextRequest, props: RouteParams) {
   // Authenticate request
   const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
   if (rateLimitResponse) return rateLimitResponse
@@ -47,4 +48,4 @@ export async function GET(request: NextRequest, props: RouteParams) {
     console.error('[Billing API] Error fetching subscription:', error)
     return createApiError('Failed to fetch subscription', 500)
   }
-}
+}, 'read')

package/dist/templates/app/api/v1/teams/[teamId]/usage/[limitSlug]/route.ts

@@ -7,6 +7,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { validateAndAuthenticateRequest, createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { SubscriptionService, UsageService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { trackUsageSchema } from '@nextsparkjs/core/lib/billing/schema'
 
@@ -14,7 +15,7 @@ interface RouteParams {
   params: Promise<{ teamId: string; limitSlug: string }>
 }
 
-export async function GET(request: NextRequest, props: RouteParams) {
+export const GET = withRateLimitTier(async function GET(request: NextRequest, props: RouteParams) {
   // Authenticate request
   const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
   if (rateLimitResponse) return rateLimitResponse
@@ -44,9 +45,9 @@ export async function GET(request: NextRequest, props: RouteParams) {
     console.error('[Billing API] Error checking quota:', error)
     return createApiError('Failed to check quota', 500)
   }
-}
+}, 'read')
 
-export async function POST(request: NextRequest, props: RouteParams) {
+export const POST = withRateLimitTier(async function POST(request: NextRequest, props: RouteParams) {
   // Authenticate request
   const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
   if (rateLimitResponse) return rateLimitResponse
@@ -88,4 +89,4 @@ export async function POST(request: NextRequest, props: RouteParams) {
     const errorMessage = error instanceof Error ? error.message : 'Failed to track usage'
     return createApiError(errorMessage, 500)
   }
-}
+}, 'write')

package/dist/templates/app/api/v1/teams/docs.md

@@ -0,0 +1,320 @@
+# Teams API
+
+Manage teams, members, subscriptions, and multi-tenancy features.
+
+## Overview
+
+The Teams API provides comprehensive team management including CRUD operations, member management, invitations, subscriptions, and usage tracking. Teams are the organizational unit for multi-tenancy, and resources are scoped to teams via Row Level Security (RLS).
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Team Endpoints
+
+### List Teams
+`GET /api/v1/teams`
+
+Returns teams the current user belongs to.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "team_abc123",
+      "name": "Acme Corp",
+      "slug": "acme-corp",
+      "avatarUrl": "/uploads/team-logo.png",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 3,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Create Team
+`POST /api/v1/teams`
+
+Create a new team. The creating user becomes the team owner.
+
+**Request Body:**
+```json
+{
+  "name": "New Team",
+  "slug": "new-team"
+}
+```
+
+### Get Team Details
+`GET /api/v1/teams/[teamId]`
+
+Returns detailed information about a specific team including member count.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "team_abc123",
+    "name": "Acme Corp",
+    "slug": "acme-corp",
+    "description": "Our main team",
+    "avatarUrl": "/uploads/logo.png",
+    "memberCount": 5,
+    "userRole": "owner",
+    "createdAt": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Update Team
+`PATCH /api/v1/teams/[teamId]`
+
+Update team settings. Requires `teams.update` permission (owner/admin).
+
+**Request Body (partial update):**
+```json
+{
+  "name": "Updated Team Name",
+  "description": "New description",
+  "avatarUrl": "/uploads/new-logo.png"
+}
+```
+
+### Delete Team
+`DELETE /api/v1/teams/[teamId]`
+
+Delete a team. Requires owner role. Personal teams cannot be deleted.
+
+---
+
+## Member Endpoints
+
+### List Team Members
+`GET /api/v1/teams/[teamId]/members`
+
+Returns all members of a team with pagination.
+
+**Query Parameters:**
+- `page` (number, optional): Page number. Default: 1
+- `limit` (number, optional): Items per page. Default: 20
+- `role` (string, optional): Filter by role (owner, admin, member, viewer)
+- `search` (string, optional): Search by name or email
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "member_123",
+      "userId": "user_456",
+      "teamId": "team_abc",
+      "role": "admin",
+      "userName": "John Doe",
+      "userEmail": "john@example.com",
+      "userImage": "/avatars/john.png",
+      "joinedAt": "2024-01-20T14:00:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 5,
+    "totalPages": 1
+  }
+}
+```
+
+### Invite Member
+`POST /api/v1/teams/[teamId]/members`
+
+Create an invitation for a new team member. Requires `members.invite` permission.
+
+**Request Body:**
+```json
+{
+  "email": "newuser@example.com",
+  "role": "member"
+}
+```
+
+**Role Hierarchy:** Users can only invite to roles at or below their own level.
+
+### Update Member Role
+`PATCH /api/v1/teams/[teamId]/members/[memberId]`
+
+Update a team member's role. Requires admin+ permissions.
+
+**Request Body:**
+```json
+{
+  "role": "admin"
+}
+```
+
+### Remove Member
+`DELETE /api/v1/teams/[teamId]/members/[memberId]`
+
+Remove a member from the team. Cannot remove the last owner.
+
+---
+
+## Invitation Endpoints
+
+### List Team Invitations
+`GET /api/v1/teams/[teamId]/invitations`
+
+Returns pending invitations for a team.
+
+**Query Parameters:**
+- `status` (string, optional): Filter by status (pending, accepted, expired)
+
+### Create Invitation
+`POST /api/v1/teams/[teamId]/invitations`
+
+Same as POST /members - creates a new invitation.
+
+---
+
+## Subscription Endpoints
+
+### Get Team Subscription
+`GET /api/v1/teams/[teamId]/subscription`
+
+Returns the team's active subscription details. Requires `billing.view` permission.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "subscription": {
+      "id": "sub_123",
+      "planId": "plan_pro",
+      "planName": "Pro",
+      "status": "active",
+      "currentPeriodEnd": "2024-03-01T00:00:00Z",
+      "cancelAtPeriodEnd": false
+    }
+  }
+}
+```
+
+---
+
+## Usage & Quota Endpoints
+
+### Check Usage Limit
+`GET /api/v1/teams/[teamId]/usage/[limitSlug]`
+
+Check current usage against plan limits.
+
+**Path Parameters:**
+- `limitSlug`: The limit identifier (e.g., "team_members", "storage_gb", "api_calls")
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "limit": "team_members",
+    "current": 4,
+    "max": 10,
+    "remaining": 6,
+    "percentage": 40
+  }
+}
+```
+
+---
+
+## Invoice Endpoints
+
+### List Team Invoices
+`GET /api/v1/teams/[teamId]/invoices`
+
+Returns billing invoices for the team.
+
+**Query Parameters:**
+- `limit` (number): Number of invoices to return
+- `status` (string): Filter by status (paid, open, void)
+
+### Get Invoice
+`GET /api/v1/teams/[teamId]/invoices/[invoiceNumber]`
+
+Returns a specific invoice with download URL.
+
+---
+
+## Utility Endpoints
+
+### Switch Active Team
+`POST /api/v1/teams/switch`
+
+Switch the user's active team context. Sets a cookie for server-side access.
+
+**Request Body:**
+```json
+{
+  "teamId": "team_abc123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "teamId": "team_abc123",
+    "message": "Active team switched successfully"
+  }
+}
+```
+
+---
+
+## Team Roles
+
+| Role | Permissions |
+|------|------------|
+| **owner** | Full access, billing, delete team, transfer ownership |
+| **admin** | Manage members, update team settings, view billing |
+| **member** | Access team resources, standard operations |
+| **viewer** | Read-only access to team resources |
+
+## Error Responses
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | VALIDATION_ERROR | Invalid parameters or request body |
+| 401 | AUTHENTICATION_FAILED | Missing or invalid authentication |
+| 403 | INSUFFICIENT_PERMISSIONS | User lacks required permissions |
+| 403 | ROLE_HIERARCHY_VIOLATION | Cannot invite to higher role |
+| 403 | NOT_TEAM_MEMBER | User is not a member of the team |
+| 403 | PERSONAL_TEAM_DELETE_FORBIDDEN | Cannot delete personal teams |
+| 404 | TEAM_NOT_FOUND | Team not found or no access |
+| 409 | ALREADY_MEMBER | User is already a team member |
+| 409 | INVITATION_EXISTS | Pending invitation already exists |
+| 409 | SLUG_EXISTS | Team slug already taken |
+
+## Related APIs
+
+- **[Users](/api/v1/users)** - User profiles and team membership
+- **[Team Invitations](/api/v1/team-invitations)** - Manage pending invitations
+- **[Billing](/api/v1/billing)** - Subscription management and checkout
+- **[API Keys](/api/v1/api-keys)** - Team-scoped API keys
+- **[Dynamic Entities](/api/v1/{entity})** - Team-scoped entity data