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

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

@@ -0,0 +1,178 @@
+/**
+ * API Presets for Teams
+ *
+ * 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/teams',
+  summary: 'Manage teams, members, subscriptions, and multi-tenancy',
+  presets: [
+    // ==================== TEAM CRUD ====================
+    {
+      id: 'list-all',
+      title: 'List My Teams',
+      description: 'Fetch all teams the current user belongs to',
+      method: 'GET',
+      queryParams: {
+        limit: '10',
+        offset: '0'
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'create-team',
+      title: 'Create New Team',
+      description: 'Create a new team (user becomes owner)',
+      method: 'POST',
+      payload: {
+        name: 'New Team',
+        slug: 'new-team'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'get-team',
+      title: 'Get Team Details',
+      description: 'Get details of a specific team',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}',
+      tags: ['read', 'detail']
+    },
+    {
+      id: 'update-team',
+      title: 'Update Team',
+      description: 'Update team name and settings',
+      method: 'PATCH',
+      path: '/{{CURRENT_TEAM_ID}}',
+      payload: {
+        name: 'Updated Team Name',
+        description: 'New team description'
+      },
+      tags: ['write', 'update']
+    },
+
+    // ==================== MEMBERS ====================
+    {
+      id: 'list-members',
+      title: 'List Team Members',
+      description: 'Get all members of the current team',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/members',
+      queryParams: {
+        page: '1',
+        limit: '20'
+      },
+      tags: ['read', 'list', 'members']
+    },
+    {
+      id: 'list-members-admins',
+      title: 'List Admins Only',
+      description: 'Filter members by admin role',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/members',
+      queryParams: {
+        role: 'admin'
+      },
+      tags: ['read', 'list', 'members', 'filter']
+    },
+    {
+      id: 'search-members',
+      title: 'Search Members',
+      description: 'Search members by name or email',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/members',
+      queryParams: {
+        search: 'john'
+      },
+      tags: ['read', 'list', 'members', 'search']
+    },
+    {
+      id: 'invite-member',
+      title: 'Invite New Member',
+      description: 'Send invitation to join team',
+      method: 'POST',
+      path: '/{{CURRENT_TEAM_ID}}/members',
+      payload: {
+        email: 'newuser@example.com',
+        role: 'member'
+      },
+      tags: ['write', 'create', 'members']
+    },
+    {
+      id: 'invite-admin',
+      title: 'Invite as Admin',
+      description: 'Invite user with admin role',
+      method: 'POST',
+      path: '/{{CURRENT_TEAM_ID}}/members',
+      payload: {
+        email: 'admin@example.com',
+        role: 'admin'
+      },
+      tags: ['write', 'create', 'members']
+    },
+
+    // ==================== INVITATIONS ====================
+    {
+      id: 'list-invitations',
+      title: 'List Pending Invitations',
+      description: 'Get all pending team invitations',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/invitations',
+      tags: ['read', 'list', 'invitations']
+    },
+
+    // ==================== SUBSCRIPTION ====================
+    {
+      id: 'get-subscription',
+      title: 'Get Team Subscription',
+      description: 'View current subscription details',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/subscription',
+      tags: ['read', 'billing']
+    },
+
+    // ==================== USAGE / QUOTAS ====================
+    {
+      id: 'check-members-usage',
+      title: 'Check Members Quota',
+      description: 'Check team member limit usage',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/usage/team_members',
+      tags: ['read', 'usage', 'quota']
+    },
+    {
+      id: 'check-storage-usage',
+      title: 'Check Storage Quota',
+      description: 'Check storage limit usage',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/usage/storage_gb',
+      tags: ['read', 'usage', 'quota']
+    },
+
+    // ==================== INVOICES ====================
+    {
+      id: 'list-invoices',
+      title: 'List Team Invoices',
+      description: 'Get billing invoices for the team',
+      method: 'GET',
+      path: '/{{CURRENT_TEAM_ID}}/invoices',
+      tags: ['read', 'billing', 'invoices']
+    },
+
+    // ==================== SWITCH TEAM ====================
+    {
+      id: 'switch-team',
+      title: 'Switch Active Team',
+      description: 'Change the active team context',
+      method: 'POST',
+      path: '/switch',
+      payload: {
+        teamId: '{{CURRENT_TEAM_ID}}'
+      },
+      tags: ['write', 'context']
+    }
+  ]
+})

package/templates/app/api/v1/teams/route.ts

@@ -10,6 +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 { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { createTeamSchema, teamListQuerySchema } from '@nextsparkjs/core/lib/teams/schema'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 import type { Team } from '@nextsparkjs/core/lib/teams/types'
@@ -21,7 +22,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/teams - List user's teams
-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)
@@ -160,10 +161,10 @@ export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse
     const response = createApiError('Internal server error', 500)
     return addCorsHeaders(response)
   }
-})
+}), 'read')
 
 // POST /api/v1/teams - Create new team
-export const POST = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
+export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
     // Authenticate using dual auth
     const authResult = await authenticateRequest(req)
@@ -290,4 +291,4 @@ export const POST = withApiLogging(async (req: NextRequest): Promise<NextRespons
     const response = createApiError('Internal server error', 500)
     return addCorsHeaders(response)
   }
-})
+}), 'write')

package/templates/app/api/v1/teams/switch/route.ts

@@ -7,6 +7,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 { TeamService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
 
@@ -20,7 +21,7 @@ export async function OPTIONS() {
 }
 
 // POST /api/v1/teams/switch - Switch active team context
-export const POST = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
+export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
     // Authenticate using dual auth
     const authResult = await authenticateRequest(req)
@@ -85,4 +86,4 @@ export const POST = withApiLogging(async (req: NextRequest): Promise<NextRespons
     const response = createApiError('Internal server error', 500)
     return addCorsHeaders(response)
   }
-})
+}), 'write')

package/templates/app/api/v1/theme/[...path]/route.ts

@@ -11,46 +11,47 @@ import {
   type ThemeRouteFile,
   type ThemeRegistryEntry
 } from '@nextsparkjs/registries/theme-registry'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
-export async function GET(
+export const GET = withRateLimitTier(async (
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
-) {
+) => {
   const { path } = await params
   return handleThemeRequest(request, path, 'GET')
-}
+}, 'read');
 
-export async function POST(
+export const POST = withRateLimitTier(async (
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
-) {
+) => {
   const { path } = await params
   return handleThemeRequest(request, path, 'POST')
-}
+}, 'write');
 
-export async function PUT(
+export const PUT = withRateLimitTier(async (
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
-) {
+) => {
   const { path } = await params
   return handleThemeRequest(request, path, 'PUT')
-}
+}, 'write');
 
-export async function DELETE(
+export const DELETE = withRateLimitTier(async (
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
-) {
+) => {
   const { path } = await params
   return handleThemeRequest(request, path, 'DELETE')
-}
+}, 'write');
 
-export async function PATCH(
+export const PATCH = withRateLimitTier(async (
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
-) {
+) => {
   const { path } = await params
   return handleThemeRequest(request, path, 'PATCH')
-}
+}, 'write');
 
 /**
  * Handle theme API requests with nested paths

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

@@ -0,0 +1,74 @@
+# Theme API
+
+Access theme metadata and route theme-specific endpoints.
+
+## Overview
+
+The Theme API provides endpoints to list installed themes and their API capabilities. Theme-specific endpoints are routed through `/api/v1/theme/{themeName}/...`.
+
+## Authentication
+
+- **GET /api/v1/theme** (list themes) is public
+- Theme-specific routes may have their own authentication requirements
+
+## Endpoints
+
+### List Themes
+`GET /api/v1/theme`
+
+Returns all registered themes with their API status and endpoints.
+
+**Response:**
+```json
+{
+  "success": true,
+  "themes": [
+    {
+      "name": "default",
+      "displayName": "Default Theme",
+      "version": "1.0.0",
+      "description": "The default NextSpark theme",
+      "hasAPI": true,
+      "apiEndpoints": [
+        {
+          "path": "/config",
+          "methods": ["GET"],
+          "description": "Get theme configuration"
+        }
+      ],
+      "baseUrl": "/api/v1/theme/default"
+    }
+  ],
+  "totalThemes": 2,
+  "activeTheme": "default",
+  "themesWithAPI": 1
+}
+```
+
+### Theme-Specific Routes
+`* /api/v1/theme/{themeName}/...`
+
+Each theme can define its own API routes. These are handled by the catch-all route and forwarded to the theme's route handlers.
+
+**Example:**
+- `GET /api/v1/theme/default/config` - Get theme config
+- `GET /api/v1/theme/blog/categories` - Get blog categories
+
+## Theme Structure
+
+Themes can expose:
+- **API Routes**: Custom endpoints under `/api/v1/theme/{name}/`
+- **Entities**: Custom entity types with their own APIs
+- **Blocks**: Page builder blocks
+- **Layouts**: Custom page layouts
+
+## Active Theme
+
+The active theme is determined by `NEXT_PUBLIC_ACTIVE_THEME` environment variable. Only the active theme's routes are accessible.
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 404 | Theme not found or route doesn't exist |
+| 500 | Server Error - Failed to list themes |

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

@@ -0,0 +1,21 @@
+/**
+ * API Presets for Theme
+ *
+ * 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/theme',
+  summary: 'Access theme metadata and API routes',
+  presets: [
+    {
+      id: 'list-themes',
+      title: 'List All Themes',
+      description: 'Get all registered themes with API status',
+      method: 'GET',
+      tags: ['read', 'list']
+    }
+  ]
+})

package/templates/app/api/v1/theme/route.ts

@@ -8,10 +8,11 @@
 import { NextResponse } from 'next/server'
 import { PluginService, type PluginRegistryEntry } from '@nextsparkjs/core/lib/services'
 import { PLUGIN_REGISTRY } from '@nextsparkjs/registries/plugin-registry'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
-export async function GET() {
+export const GET = withRateLimitTier(async () => {
   return listPluginsWithAPI()
-}
+}, 'read');
 
 /**
  * List all plugins with their API status

package/templates/app/api/v1/users/[id]/meta/[key]/route.ts

@@ -30,6 +30,7 @@ import {
 } from '@nextsparkjs/core/lib/api/helpers'
 import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { z } from 'zod'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 // Validation schema for metadata value
 const metadataValueSchema = z.object({
@@ -56,7 +57,7 @@ export async function OPTIONS() {
  * GET /api/v1/users/user-123/meta/theme
  * Response: { success: true, data: { key: "theme", value: "dark" } }
  */
-export const GET = withApiLogging(async (
+export const GET = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string; key: string }> }
 ): Promise<NextResponse> => {
@@ -140,7 +141,7 @@ export const GET = withApiLogging(async (
     )
     return addCorsHeaders(response)
   }
-})
+}), 'read');
 
 /**
  * PUT /api/v1/users/:id/meta/:key
@@ -159,7 +160,7 @@ export const GET = withApiLogging(async (
  * Body: { value: "dark", isPublic: false }
  * Response: { success: true, data: { key: "theme", value: "dark", updated: true } }
  */
-export const PUT = withApiLogging(async (
+export const PUT = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string; key: string }> }
 ): Promise<NextResponse> => {
@@ -270,7 +271,7 @@ export const PUT = withApiLogging(async (
     )
     return addCorsHeaders(response)
   }
-})
+}), 'write');
 
 /**
  * PATCH /api/v1/users/:id/meta/:key
@@ -287,7 +288,7 @@ export const PATCH = PUT
  * DELETE /api/v1/users/user-123/meta/theme
  * Response: { success: true, data: { key: "theme", deleted: true } }
  */
-export const DELETE = withApiLogging(async (
+export const DELETE = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string; key: string }> }
 ): Promise<NextResponse> => {
@@ -360,4 +361,4 @@ export const DELETE = withApiLogging(async (
     )
     return addCorsHeaders(response)
   }
-})
+}), 'write');

package/templates/app/api/v1/users/[id]/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { queryOneWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db';
-import { 
-  createApiResponse, 
+import {
+  createApiResponse,
   createApiError,
   withApiLogging,
   handleCorsPreflightRequest,
@@ -13,6 +13,7 @@ import {
 } from '@nextsparkjs/core/lib/api/helpers';
 import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { z } from 'zod';
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
 
 const updateUserSchema = z.object({
   firstName: z.string().min(1).optional(),
@@ -28,7 +29,7 @@ export async function OPTIONS() {
 }
 
 // GET /api/v1/users/:id - Get specific user
-export const GET = withApiLogging(async (
+export const GET = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
@@ -87,10 +88,10 @@ export const GET = withApiLogging(async (
     const response = createApiError('Internal server error', 500);
     return addCorsHeaders(response);
   }
-});
+}), 'read');
 
 // PATCH /api/v1/users/:id - Update user
-export const PATCH = withApiLogging(async (
+export const PATCH = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
@@ -224,10 +225,10 @@ export const PATCH = withApiLogging(async (
     const response = createApiError('Internal server error', 500);
     return addCorsHeaders(response);
   }
-});
+}), 'write');
 
 // DELETE /api/v1/users/:id - Delete user
-export const DELETE = withApiLogging(async (
+export const DELETE = withRateLimitTier(withApiLogging(async (
   req: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
@@ -299,4 +300,4 @@ export const DELETE = withApiLogging(async (
     const response = createApiError('Internal server error', 500);
     return addCorsHeaders(response);
   }
-});
+}), 'write');

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

@@ -0,0 +1,93 @@
+# Users API
+
+Manage user profiles and account settings.
+
+## Overview
+
+The Users API allows you to view and update user profile information. Users can update their own profile, while admins can manage other users within their team.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### Get Current User
+`GET /api/v1/users/me`
+
+Returns the currently authenticated user's profile.
+
+**Example Response:**
+```json
+{
+  "id": "user_123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "image": "/uploads/avatar.png",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "teams": [
+    {
+      "id": "team_456",
+      "name": "Acme Corp",
+      "role": "admin"
+    }
+  ]
+}
+```
+
+### Update Current User
+`PATCH /api/v1/users/me`
+
+Update the current user's profile.
+
+**Request Body:**
+```json
+{
+  "name": "John Smith",
+  "image": "/uploads/new-avatar.png"
+}
+```
+
+### List Team Members
+`GET /api/v1/users`
+
+Returns all users in the current team.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `search` (string, optional): Search by name or email
+
+### Get User by ID
+`GET /api/v1/users/[id]`
+
+Returns a specific user's profile (within the same team).
+
+**Path Parameters:**
+- `id` (string, required): User ID
+
+## User Roles
+
+Team-level roles determine permissions:
+- `member` - Basic team member
+- `admin` - Can manage team settings and members
+- `owner` - Full control of the team
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - User doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Auth](/api/v1/auth)** - Authentication and session management
+- **[Teams](/api/v1/teams)** - Team membership and roles
+- **[Team Invitations](/api/v1/team-invitations)** - Invite users to teams
+- **[API Keys](/api/v1/api-keys)** - Manage programmatic access

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

@@ -0,0 +1,59 @@
+/**
+ * API Presets for Users
+ *
+ * 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/users',
+  summary: 'Manage user profiles and team members',
+  presets: [
+    {
+      id: 'get-me',
+      title: 'Get Current User',
+      description: 'Fetch the currently authenticated user profile',
+      method: 'GET',
+      pathParams: {
+        id: 'me'
+      },
+      tags: ['read', 'profile']
+    },
+    {
+      id: 'list-team-members',
+      title: 'List Team Members',
+      description: 'Fetch all users in the current team',
+      method: 'GET',
+      params: {
+        limit: 20,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'update-profile',
+      title: 'Update My Profile',
+      description: 'Update current user name',
+      method: 'PATCH',
+      pathParams: {
+        id: 'me'
+      },
+      payload: {
+        name: 'Updated Name'
+      },
+      tags: ['write', 'profile']
+    },
+    {
+      id: 'search-users',
+      title: 'Search Team Members',
+      description: 'Search users by name or email',
+      method: 'GET',
+      params: {
+        search: 'john',
+        limit: 10
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})