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

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

@@ -0,0 +1,50 @@
+/**
+ * Team Subscription API
+ *
+ * GET /api/v1/teams/[teamId]/subscription - Get team's active subscription
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { validateAndAuthenticateRequest, createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
+
+interface RouteParams {
+  params: Promise<{ teamId: string }>
+}
+
+export async function GET(request: NextRequest, props: RouteParams) {
+  // Authenticate request
+  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  if (rateLimitResponse) return rateLimitResponse
+
+  const { teamId } = await props.params
+
+  try {
+    // Check if user has permission to view subscription using MembershipService
+    const membership = await MembershipService.get(auth.userId, teamId)
+    const actionResult = membership.canPerformAction('billing.view')
+
+    if (!actionResult.allowed) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: actionResult.message,
+          reason: actionResult.reason,
+          meta: actionResult.meta,
+        },
+        { status: 403 }
+      )
+    }
+
+    const subscription = await SubscriptionService.getActive(teamId)
+
+    if (!subscription) {
+      return createApiError('No active subscription found for this team', 404)
+    }
+
+    return createApiResponse({ subscription })
+  } catch (error) {
+    console.error('[Billing API] Error fetching subscription:', error)
+    return createApiError('Failed to fetch subscription', 500)
+  }
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Team Usage API
+ *
+ * GET /api/v1/teams/[teamId]/usage/[limitSlug] - Get quota info
+ * POST /api/v1/teams/[teamId]/usage/[limitSlug] - Track usage
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { validateAndAuthenticateRequest, createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { SubscriptionService, UsageService, MembershipService } from '@nextsparkjs/core/lib/services'
+import { trackUsageSchema } from '@nextsparkjs/core/lib/billing/schema'
+
+interface RouteParams {
+  params: Promise<{ teamId: string; limitSlug: string }>
+}
+
+export async function GET(request: NextRequest, props: RouteParams) {
+  // Authenticate request
+  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  if (rateLimitResponse) return rateLimitResponse
+
+  const { teamId, limitSlug } = await props.params
+
+  try {
+    // Check if user has permission to view usage using MembershipService
+    const membership = await MembershipService.get(auth.userId, teamId)
+    const actionResult = membership.canPerformAction('billing.view')
+
+    if (!actionResult.allowed) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: actionResult.message,
+          reason: actionResult.reason,
+          meta: actionResult.meta,
+        },
+        { status: 403 }
+      )
+    }
+
+    const quota = await SubscriptionService.checkQuota(teamId, limitSlug)
+    return createApiResponse(quota)
+  } catch (error) {
+    console.error('[Billing API] Error checking quota:', error)
+    return createApiError('Failed to check quota', 500)
+  }
+}
+
+export async function POST(request: NextRequest, props: RouteParams) {
+  // Authenticate request
+  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  if (rateLimitResponse) return rateLimitResponse
+
+  const { teamId, limitSlug } = await props.params
+
+  try {
+    // Check if user has permission to track usage using MembershipService
+    const membership = await MembershipService.get(auth.userId, teamId)
+    const actionResult = membership.canPerformAction('billing.manage')
+
+    if (!actionResult.allowed) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: actionResult.message,
+          reason: actionResult.reason,
+          meta: actionResult.meta,
+        },
+        { status: 403 }
+      )
+    }
+
+    const body = await request.json()
+    const data = trackUsageSchema.parse({
+      ...body,
+      limitSlug,
+    })
+
+    const result = await UsageService.track({
+      ...data,
+      teamId,
+      userId: auth.userId,
+    })
+
+    return createApiResponse(result, { created: true }, 201)
+  } catch (error: unknown) {
+    console.error('[Billing API] Error tracking usage:', error)
+    const errorMessage = error instanceof Error ? error.message : 'Failed to track usage'
+    return createApiError(errorMessage, 500)
+  }
+}

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

package/dist/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']
+    }
+  ]
+})