@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.82

package/templates/app/api/v1/api-keys/presets.ts

@@ -0,0 +1,31 @@
+/**
+ * API Presets for API Keys
+ *
+ * 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/api-keys',
+  summary: 'Manage API keys for programmatic access',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List API Keys',
+      description: 'Fetch all API keys for the current team',
+      method: 'GET',
+      tags: ['read', 'list']
+    },
+    {
+      id: 'create-key',
+      title: 'Create API Key',
+      description: 'Create a new API key for the team',
+      method: 'POST',
+      payload: {
+        name: 'My New API Key'
+      },
+      tags: ['write', 'create']
+    }
+  ]
+})

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/billing/docs.md

@@ -0,0 +1,209 @@
+# Billing API
+
+Manage subscriptions, plans, and billing operations for teams.
+
+## Overview
+
+The Billing API integrates with Stripe to handle subscription management, checkout sessions, plan changes, and customer portal access. All billing operations are scoped to teams.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+The `x-team-id` header or user's default team is used for team context.
+
+## Endpoints
+
+### List Plans
+`GET /api/v1/billing/plans`
+
+Returns available subscription plans. Public plans visible to all, hidden plans only to superadmin.
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "plan_123",
+      "slug": "pro",
+      "name": "Pro Plan",
+      "description": "For growing teams",
+      "priceMonthly": 29,
+      "priceYearly": 290,
+      "currency": "USD",
+      "features": ["unlimited_projects", "api_access"],
+      "limits": {
+        "team_members": 10,
+        "storage_gb": 100
+      }
+    }
+  ]
+}
+```
+
+### Create Checkout Session
+`POST /api/v1/billing/checkout`
+
+Creates a Stripe Checkout session for subscription upgrade. Returns a URL to redirect the user.
+
+**Required Permission:** `billing.checkout` (team owner/admin)
+
+**Request Body:**
+```json
+{
+  "planSlug": "pro",
+  "billingPeriod": "monthly"
+}
+```
+
+**Parameters:**
+- `planSlug` (string, required): The plan to subscribe to
+- `billingPeriod` (string): "monthly" or "yearly" (default: "monthly")
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "url": "https://checkout.stripe.com/...",
+    "sessionId": "cs_live_..."
+  }
+}
+```
+
+### Open Customer Portal
+`GET /api/v1/billing/portal`
+
+Creates a Stripe Customer Portal session for managing payment methods and viewing invoices.
+
+**Required Permission:** `billing.portal` (team owner/admin)
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "url": "https://billing.stripe.com/..."
+  }
+}
+```
+
+### Change Plan
+`POST /api/v1/billing/change-plan`
+
+Change the current subscription to a different plan.
+
+**Required Permission:** `billing.change_plan` (team owner/admin)
+
+**Request Body:**
+```json
+{
+  "planSlug": "enterprise",
+  "billingPeriod": "yearly"
+}
+```
+
+### Cancel Subscription
+`POST /api/v1/billing/cancel`
+
+Cancel the current subscription. Cancellation takes effect at the end of the billing period.
+
+**Required Permission:** `billing.cancel` (team owner/admin)
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "canceledAt": "2024-02-01T00:00:00Z",
+    "effectiveDate": "2024-02-28T23:59:59Z"
+  }
+}
+```
+
+### Check Action Permission
+`POST /api/v1/billing/check-action`
+
+Verify if the current user can perform a specific action based on RBAC, plan features, and quotas.
+
+**Request Body:**
+```json
+{
+  "action": "team.invite_member",
+  "teamId": "team_123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "allowed": true,
+    "reason": null
+  }
+}
+```
+
+Or if not allowed:
+```json
+{
+  "success": true,
+  "data": {
+    "allowed": false,
+    "reason": "quota_exceeded",
+    "message": "Team member limit reached",
+    "meta": {
+      "limit": 5,
+      "current": 5
+    }
+  }
+}
+```
+
+### Stripe Webhook
+`POST /api/v1/billing/webhooks/stripe`
+
+Handles Stripe webhook events for subscription lifecycle management.
+
+**Note:** This endpoint is called by Stripe, not by your application. It requires Stripe signature verification.
+
+**Handled Events:**
+- `checkout.session.completed` - New subscription created
+- `customer.subscription.updated` - Plan changed
+- `customer.subscription.deleted` - Subscription canceled
+- `invoice.paid` - Payment successful
+- `invoice.payment_failed` - Payment failed
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters or missing required fields |
+| 401 | Unauthorized - Authentication required |
+| 403 | Forbidden - Insufficient permissions or plan doesn't allow action |
+| 404 | Not Found - Plan or subscription not found |
+| 500 | Server Error - Stripe API error or internal error |
+
+## Billing Period Proration
+
+When changing plans mid-cycle:
+- **Upgrade:** Prorated charge for the difference
+- **Downgrade:** Credit applied to next invoice
+- **Same price:** No proration
+
+## Test Mode
+
+In development, Stripe test mode is used. Test card numbers:
+- Success: `4242 4242 4242 4242`
+- Decline: `4000 0000 0000 0002`
+- 3D Secure: `4000 0025 0000 3155`
+
+## Related APIs
+
+- **[Teams](/api/v1/teams)** - Team subscription and usage endpoints
+- **[Teams Subscription](/api/v1/teams/{teamId}/subscription)** - View team's current subscription
+- **[Teams Usage](/api/v1/teams/{teamId}/usage/{limit})** - Check quota usage
+- **[Teams Invoices](/api/v1/teams/{teamId}/invoices)** - View billing invoices

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

@@ -0,0 +1,121 @@
+/**
+ * API Presets for Billing
+ *
+ * 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/billing',
+  summary: 'Manage subscriptions, plans, and billing operations',
+  presets: [
+    // Plans
+    {
+      id: 'list-plans',
+      title: 'List Plans',
+      description: 'Fetch all available subscription plans',
+      method: 'GET',
+      tags: ['read', 'plans']
+    },
+
+    // Checkout
+    {
+      id: 'checkout-pro-monthly',
+      title: 'Checkout Pro (Monthly)',
+      description: 'Create checkout session for Pro plan monthly',
+      method: 'POST',
+      payload: {
+        planSlug: 'pro',
+        billingPeriod: 'monthly'
+      },
+      tags: ['write', 'checkout']
+    },
+    {
+      id: 'checkout-pro-yearly',
+      title: 'Checkout Pro (Yearly)',
+      description: 'Create checkout session for Pro plan yearly (save 20%)',
+      method: 'POST',
+      payload: {
+        planSlug: 'pro',
+        billingPeriod: 'yearly'
+      },
+      tags: ['write', 'checkout']
+    },
+    {
+      id: 'checkout-enterprise',
+      title: 'Checkout Enterprise',
+      description: 'Create checkout session for Enterprise plan',
+      method: 'POST',
+      payload: {
+        planSlug: 'enterprise',
+        billingPeriod: 'yearly'
+      },
+      tags: ['write', 'checkout']
+    },
+
+    // Portal
+    {
+      id: 'open-portal',
+      title: 'Open Customer Portal',
+      description: 'Get URL for Stripe customer portal',
+      method: 'GET',
+      tags: ['read', 'portal']
+    },
+
+    // Change Plan
+    {
+      id: 'upgrade-to-pro',
+      title: 'Upgrade to Pro',
+      description: 'Change current subscription to Pro plan',
+      method: 'POST',
+      payload: {
+        planSlug: 'pro',
+        billingPeriod: 'monthly'
+      },
+      tags: ['write', 'change-plan']
+    },
+
+    // Cancel
+    {
+      id: 'cancel-subscription',
+      title: 'Cancel Subscription',
+      description: 'Cancel current subscription at end of billing period',
+      method: 'POST',
+      payload: {},
+      tags: ['write', 'cancel']
+    },
+
+    // Check Action
+    {
+      id: 'check-invite-member',
+      title: 'Check: Can Invite Member',
+      description: 'Check if team can invite more members (quota check)',
+      method: 'POST',
+      payload: {
+        action: 'team.invite_member'
+      },
+      tags: ['read', 'check-action']
+    },
+    {
+      id: 'check-create-project',
+      title: 'Check: Can Create Project',
+      description: 'Check if team can create more projects',
+      method: 'POST',
+      payload: {
+        action: 'projects.create'
+      },
+      tags: ['read', 'check-action']
+    },
+    {
+      id: 'check-api-access',
+      title: 'Check: API Access',
+      description: 'Check if plan includes API access feature',
+      method: 'POST',
+      payload: {
+        action: 'api.access'
+      },
+      tags: ['read', 'check-action']
+    }
+  ]
+})