@teamvortexsoftware/vortex-nextjs-15-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,454 +1,224 @@
 # Vortex Next.js 15 SDK
 
-A Next.js SDK that provides API route handlers for Vortex functionality. This SDK wraps the `@teamvortexsoftware/vortex-node-22-sdk` to help integrate Vortex into your Next.js applications.
+Drop-in Next.js integration for Vortex invitations and JWT functionality. Get up and running in under 2 minutes!
 
-## ⚠️ SECURITY NOTICE
-
-**This SDK requires proper security configuration before production use:**
-- ✋ **All invitation endpoints require access control hooks to be configured**
-- ✋ **JWT endpoints require authentication hooks to be configured**
-- ✋ **No endpoints are secured by default - you must implement authorization**
-- ✋ **Input sanitization and rate limiting should be implemented**
-- ✋ **Error messages are sanitized but you should implement proper logging**
-
-**This is NOT a drop-in solution - it requires security implementation by you.**
-
-## Installation
+## 🚀 Quick Start
 
 ```bash
-npm install @teamvortexsoftware/vortex-nextjs-15-sdk
+npm install @teamvortexsoftware/vortex-nextjs-15-sdk @teamvortexsoftware/vortex-react-provider
+npx vortex-setup
 ```
 
-## Configuration
-
-Configure Vortex in your application:
-
-### Environment Variables
-Set the following environment variables:
-```bash
-VORTEX_API_KEY=your_api_key
-VORTEX_API_BASE_URL=https://api.vortexsoftware.com  # optional
-```
-
-### Security Configuration (REQUIRED)
-
-**CRITICAL**: You MUST configure authentication and access control hooks for ALL endpoints to work securely.
-
-#### Complete Security Configuration
-
-1. Create a configuration file: `lib/vortex-config.ts`
-```typescript
-import { configureVortex, type AuthenticatedUser, type AccessControlHook } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-import { NextRequest } from 'next/server';
-
-configureVortex({
-  apiKey: process.env.VORTEX_API_KEY!,
-
-  // Required for JWT generation
-  authenticateUser: async (request: NextRequest): Promise<AuthenticatedUser | null> => {
-    // Your authentication logic - get user from session, JWT, etc.
-    const user = await getCurrentUser(request);
-
-    return user ? {
-      userId: user.id,
-      identifiers: [{ type: 'email', value: user.email }],
-      groups: user.groups || [],
-      role: user.role
-    } : null;
-  },
-
-  // Required for invitation endpoints - implement all that you plan to use
-  canAccessInvitationsByTarget: async (request, user, resource) => {
-    // Check if user can access invitations for the target
-    return user && await canUserAccessTarget(user, resource);
-  },
+That's it! The setup wizard creates all required files automatically.
 
-  canAccessInvitation: async (request, user, resource) => {
-    // Check if user can access this specific invitation
-    return user && await canUserAccessInvitation(user, resource.invitationId);
-  },
-
-  canDeleteInvitation: async (request, user, resource) => {
-    // Check if user can delete this invitation (e.g., admin only)
-    return user && user.role === 'admin' && await canUserAccessInvitation(user, resource.invitationId);
-  },
+## ⚡ What You Get
 
-  canAcceptInvitations: async (request, user, resource) => {
-    // Check if user can accept these invitations
-    return user && await canUserAcceptInvitations(user, resource.invitationIds);
-  },
+- **JWT Authentication**: Secure user authentication with Vortex
+- **Invitation Management**: Create, accept, and manage invitations
+- **Full Node.js SDK Access**: All `@teamvortexsoftware/vortex-node-22-sdk` functionality
+- **TypeScript Support**: Fully typed with IntelliSense
+- **React Integration**: Works seamlessly with `@teamvortexsoftware/vortex-react-provider`
 
-  canAccessInvitationsByGroup: async (request, user, resource) => {
-    // Check if user can access invitations for this group
-    return user && await canUserAccessGroup(user, resource.groupType, resource.groupId);
-  },
+## 📁 Generated Files
 
-  canDeleteInvitationsByGroup: async (request, user, resource) => {
-    // Check if user can delete invitations for this group
-    return user && user.role === 'admin' && await canUserAccessGroup(user, resource.groupType, resource.groupId);
-  },
+After running `npx vortex-setup`, you'll have:
 
-  canReinvite: async (request, user, resource) => {
-    // Check if user can resend this invitation
-    return user && await canUserReinvite(user, resource.invitationId);
-  }
-});
 ```
+app/api/vortex/
+├── jwt/route.ts                                    # JWT generation
+├── invitations/route.ts                            # Get invitations by target
+├── invitations/accept/route.ts                     # Accept invitations
+├── invitations/[invitationId]/route.ts            # Get/delete single invitation
+├── invitations/[invitationId]/reinvite/route.ts   # Resend invitation
+└── invitations/by-group/[groupType]/[groupId]/route.ts  # Group operations
 
-**⚠️ WARNING**: If any access control hook is missing, that endpoint will fail with 403 unless the user is authenticated. This is by design for security.
-
-2. Import it in your root layout: `app/layout.tsx`
-```typescript
-import '../lib/vortex-config'; // Initialize Vortex configuration
-
-export default function RootLayout({ children }) {
-  return <html><body>{children}</body></html>;
-}
+lib/
+└── vortex-config.ts                               # Your configuration
 ```
 
-#### For Invitations Only (No Authentication Hook Needed)
-```bash
-# Just set environment variables
-VORTEX_API_KEY=your_api_key
-```
-
-📖 **For detailed configuration options and authentication examples (NextAuth.js, Supabase, custom JWT), see [CONFIGURATION_GUIDE.md](./CONFIGURATION_GUIDE.md)**
-
-## Setting Up API Routes
-
-This SDK provides convenience functions to create Next.js API route handlers. Create the following files in your Next.js app directory:
-
-⚠️ **IMPORTANT - Access Control Required**: The invitation management endpoints do not implement authorization checks. You must add your own access controls to ensure users can only access invitations they are authorized to see. The SDK only handles the Vortex API communication - authorization is your responsibility.
-
-### 1. JWT Generation Route
-**File:** `app/api/vortex/jwt/route.ts`
+Each route file is just 3 lines:
 ```typescript
-import { createVortexJwtRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
+import 'lib/vortex-config';
+import { createVortexRoutes } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
 
-export const POST = createVortexJwtRoute();
+export const { GET, DELETE } = createVortexRoutes().invitation;
 ```
 
-### 2. Get Invitations by Target
-**File:** `app/api/vortex/invitations/route.ts`
-```typescript
-import { createVortexInvitationsRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
+## ⚙️ Configuration
 
-export const { GET } = createVortexInvitationsRoute();
+### 1. Environment Variables
+Add to your `.env.local`:
+```bash
+VORTEX_API_KEY=your_api_key_here
 ```
 
-**With Access Control Example:**
+### 2. App Layout
+Import the config in your `app/layout.tsx`:
 ```typescript
-import { NextRequest } from 'next/server';
-import { handleGetInvitationsByTarget, createErrorResponse } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export async function GET(request: NextRequest) {
-  // Add your authorization logic here
-  const user = await getCurrentUser(request);
-
-  if (!user) {
-    return createErrorResponse('Unauthorized', 401);
-  }
+import '../lib/vortex-config'; // Add this line
 
-  // Additional checks - ensure user can access the requested target
-  const targetValue = request.nextUrl.searchParams.get('targetValue');
-  if (!canUserAccessTarget(user, targetValue)) {
-    return createErrorResponse('Forbidden', 403);
-  }
-
-  return handleGetInvitationsByTarget(request);
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <VortexProvider config={{ apiBaseUrl: '/api/vortex' }}>
+          {children}
+        </VortexProvider>
+      </body>
+    </html>
+  );
 }
 ```
 
-### 3. Individual Invitation Management
-**File:** `app/api/vortex/invitations/[invitationId]/route.ts`
-```typescript
-import { createVortexInvitationRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export const { GET, DELETE } = createVortexInvitationRoute();
-```
+### 3. Customize Configuration
+Edit `lib/vortex-config.ts` to implement your authentication and access control:
 
-**With Access Control Example:**
 ```typescript
-import { NextRequest } from 'next/server';
-import { handleGetInvitation, handleRevokeInvitation, createErrorResponse } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export async function GET(request: NextRequest, { params }: { params: { invitationId: string } }) {
-  const user = await getCurrentUser(request);
-
-  if (!user || !await canUserAccessInvitation(user, params.invitationId)) {
-    return createErrorResponse('Unauthorized', 401);
-  }
-
-  return handleGetInvitation(request, params.invitationId);
-}
-
-export async function DELETE(request: NextRequest, { params }: { params: { invitationId: string } }) {
-  const user = await getCurrentUser(request);
+import { configureVortexLazy, createAllowAllAccessControl } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
 
-  if (!user || !await canUserDeleteInvitation(user, params.invitationId)) {
-    return createErrorResponse('Unauthorized', 401);
-  }
-
-  return handleRevokeInvitation(request, params.invitationId);
-}
-```
-
-### 4. Accept Invitations
-**File:** `app/api/vortex/invitations/accept/route.ts`
-```typescript
-import { createVortexInvitationsAcceptRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export const { POST } = createVortexInvitationsAcceptRoute();
-```
-
-### 5. Group-based Invitation Management
-**File:** `app/api/vortex/invitations/by-group/[groupType]/[groupId]/route.ts`
-```typescript
-import { createVortexInvitationsByGroupRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export const { GET, DELETE } = createVortexInvitationsByGroupRoute();
-```
-
-**With Access Control Example:**
-```typescript
-import { NextRequest } from 'next/server';
-import { handleGetInvitationsByGroup, handleDeleteInvitationsByGroup, createErrorResponse } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export async function GET(request: NextRequest, { params }: { params: { groupType: string; groupId: string } }) {
-  const user = await getCurrentUser(request);
-
-  if (!user || !await canUserAccessGroup(user, params.groupType, params.groupId)) {
-    return createErrorResponse('Unauthorized', 401);
-  }
-
-  return handleGetInvitationsByGroup(request, params.groupType, params.groupId);
-}
-
-export async function DELETE(request: NextRequest, { params }: { params: { groupType: string; groupId: string } }) {
-  const user = await getCurrentUser(request);
+configureVortexLazy(async () => ({
+  apiKey: process.env.VORTEX_API_KEY!,
 
-  if (!user || !await canUserManageGroup(user, params.groupType, params.groupId)) {
-    return createErrorResponse('Unauthorized', 401);
-  }
+  // Required: How to authenticate users
+  authenticateUser: async (request) => {
+    const user = await getCurrentUser(request); // Your auth logic
+    return user ? {
+      userId: user.id,
+      identifiers: [{ type: 'email', value: user.email }],
+      groups: user.groups, // [{ type: 'team', groupId: '123', name: 'My Team' }]
+    } : null;
+  },
 
-  return handleDeleteInvitationsByGroup(request, params.groupType, params.groupId);
-}
+  // Simple: Allow all operations (customize for production)
+  ...createAllowAllAccessControl(),
+}));
 ```
 
-### 6. Reinvite
-**File:** `app/api/vortex/invitations/[invitationId]/reinvite/route.ts`
-```typescript
-import { createVortexReinviteRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
+## 🔧 Production Security
 
-export const { POST } = createVortexReinviteRoute();
-```
+For production apps, replace `createAllowAllAccessControl()` with proper authorization:
 
-**With Access Control Example:**
 ```typescript
-import { NextRequest } from 'next/server';
-import { handleReinvite, createErrorResponse } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
+configureVortexLazy(async () => ({
+  apiKey: process.env.VORTEX_API_KEY!,
+  authenticateUser: async (request) => { /* your auth */ },
 
-export async function POST(request: NextRequest, { params }: { params: { invitationId: string } }) {
-  const user = await getCurrentUser(request);
+  // Custom access control
+  canDeleteInvitation: async (request, user, resource) => {
+    return user?.role === 'admin'; // Only admins can delete
+  },
 
-  if (!user || !await canUserReinvite(user, params.invitationId)) {
-    return createErrorResponse('Unauthorized', 401);
-  }
+  canAccessInvitationsByGroup: async (request, user, resource) => {
+    return user?.groups.some(g =>
+      g.type === resource?.groupType && g.groupId === resource?.groupId
+    );
+  },
 
-  return handleReinvite(request, params.invitationId);
-}
+  // ... other access control hooks
+}));
 ```
 
-## API Endpoints
-
-Once set up, your Next.js app will expose the following API endpoints:
-
-### JWT Generation
-- **POST** `/api/vortex/jwt`
-- Generates JWT token for the authenticated user making the request
-
-**Authentication Required**: This endpoint requires the `authenticateUser` hook to be configured. The JWT will be generated using data from your authenticated user, not from request body data.
-
-**Request**: No request body required. User information is obtained through your authentication hook.
-
-**Response:**
-```json
-{
-  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-}
-```
+## 📚 API Endpoints
 
-**Error Responses:**
-- `401 Unauthorized`: User is not authenticated
-- `500 Internal Server Error`: Missing authenticateUser configuration
+Your app automatically gets these API routes:
 
-### Invitations Management
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/vortex/jwt` | POST | Generate JWT for authenticated user |
+| `/api/vortex/invitations` | GET | Get invitations by target (email/phone) |
+| `/api/vortex/invitations/accept` | POST | Accept multiple invitations |
+| `/api/vortex/invitations/[id]` | GET/DELETE | Get or delete specific invitation |
+| `/api/vortex/invitations/[id]/reinvite` | POST | Resend invitation |
+| `/api/vortex/invitations/by-group/[type]/[id]` | GET/DELETE | Group-based operations |
 
-#### Get Invitations by Target
-- **GET** `/api/vortex/invitations?targetType=email&targetValue=user@example.com`
-- Supported `targetType`: `email`, `username`, `phoneNumber`
+## 🎯 Common Use Cases
 
-#### Get Specific Invitation
-- **GET** `/api/vortex/invitations/{invitationId}`
+### Frontend: Get User's JWT
+```typescript
+import { useVortexJWT } from '@teamvortexsoftware/vortex-react-provider';
 
-#### Revoke Invitation
-- **DELETE** `/api/vortex/invitations/{invitationId}`
+function MyComponent() {
+  const { jwt, isLoading } = useVortexJWT();
 
-#### Accept Invitations
-- **POST** `/api/vortex/invitations/accept`
+  if (isLoading) return <div>Loading...</div>;
+  if (!jwt) return <div>Not authenticated</div>;
 
-**Request Body:**
-```json
-{
-  "invitationIds": ["inv-123", "inv-456"],
-  "target": {
-    "type": "email",
-    "value": "user@example.com"
-  }
+  return <div>Authenticated! JWT: {jwt.substring(0, 20)}...</div>;
 }
 ```
 
-#### Get Invitations by Group
-- **GET** `/api/vortex/invitations/by-group/{groupType}/{groupId}`
-
-#### Delete Invitations by Group
-- **DELETE** `/api/vortex/invitations/by-group/{groupType}/{groupId}`
-
-#### Resend Invitation
-- **POST** `/api/vortex/invitations/{invitationId}/reinvite`
-
-## Advanced Usage
-
-### Custom Route Handlers
-If you need more control, you can use the individual handler functions:
-
+### Frontend: Manage Invitations
 ```typescript
-import { NextRequest } from 'next/server';
-import { handleJwtGeneration } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
-
-export async function POST(request: NextRequest) {
-  // Add custom logic here (e.g., authentication, logging)
+const { data: invitations } = useFetch('/api/vortex/invitations/by-group/team/my-team-id');
 
-  return handleJwtGeneration(request);
-}
+// Delete invitation
+await fetch(`/api/vortex/invitations/${invitationId}`, { method: 'DELETE' });
 ```
 
-### Direct SDK Access
-You can also use the underlying Vortex SDK directly:
-
+### Backend: Direct SDK Usage
 ```typescript
 import { Vortex } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
 
+// All Node.js SDK functionality is available
 const vortex = new Vortex(process.env.VORTEX_API_KEY!);
-const jwt = vortex.generateJwt({
-  userId: 'user-123',
-  identifiers: [{ type: 'email', value: 'user@example.com' }],
-  groups: [{ type: 'org', id: 'org-123', name: 'My Org' }]
-});
+const invitations = await vortex.getInvitationsByGroup('team', 'team-123');
 ```
 
-## Implementing Access Controls
-
-**CRITICAL**: You must implement your own authorization logic for all invitation endpoints. The SDK does not make authorization decisions - it only handles Vortex API communication.
+## 🛠️ Advanced: Custom Routes
 
-### Common Access Control Patterns
+Need custom logic? Create your own routes:
 
-#### Resource Ownership
 ```typescript
-async function canUserAccessInvitation(user: any, invitationId: string): Promise<boolean> {
-  // Check if the invitation belongs to the user's organization
-  const invitation = await getInvitationFromDatabase(invitationId);
-  return invitation && user.organizationIds.includes(invitation.organizationId);
-}
-```
-
-#### Role-Based Access
-```typescript
-async function canUserDeleteInvitation(user: any, invitationId: string): Promise<boolean> {
-  // Only admins can delete invitations
-  return user.role === 'admin' && await canUserAccessInvitation(user, invitationId);
-}
-```
+// app/api/custom-invitation/route.ts
+import 'lib/vortex-config';
+import { handleGetInvitation, createErrorResponse } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
 
-#### Group Membership
-```typescript
-async function canUserAccessGroup(user: any, groupType: string, groupId: string): Promise<boolean> {
-  // Check if user is a member of the group
-  return user.groups.some(group =>
-    group.type === groupType && group.id === groupId
-  );
-}
-```
-
-### Access Control Checklist
-
-For each endpoint, consider:
-- ✅ **Authentication**: Is the user logged in?
-- ✅ **Resource Ownership**: Does the user own or have access to this resource?
-- ✅ **Permission Level**: Does the user have the right permissions for this action?
-- ✅ **Rate Limiting**: Should this endpoint be rate limited?
-- ✅ **Audit Logging**: Should this action be logged?
-
-## Error Handling
-
-All API routes return standardized error responses:
+export async function GET(request: NextRequest) {
+  // Add custom validation
+  const user = await validateUser(request);
+  if (!user.isAdmin) {
+    return createErrorResponse('Admin required', 403);
+  }
 
-```json
-{
-  "error": "Error message here"
+  // Use SDK handler
+  return handleGetInvitation(request, 'invitation-id');
 }
 ```
 
-Common HTTP status codes:
-- `400`: Bad Request (missing required fields, invalid parameters)
-- `401`: Unauthorized (authentication required)
-- `403`: Forbidden (insufficient permissions)
-- `405`: Method Not Allowed
-- `429`: Too Many Requests (if you implement rate limiting)
-- `500`: Internal Server Error
-
-## Rate Limiting & Security Best Practices
+## 🆘 Troubleshooting
 
-**CRITICAL**: Implement rate limiting to prevent abuse. Here are examples:
-
-### With `@upstash/ratelimit`
-```typescript
-import { Ratelimit } from '@upstash/ratelimit';
-import { Redis } from '@upstash/redis';
+### Build Errors
+If you see configuration errors during build:
+- Make sure you're importing `'lib/vortex-config'` in your layout
+- Check that your `.env.local` has `VORTEX_API_KEY`
+- Ensure you're using lazy initialization (`configureVortexLazy`)
 
-const ratelimit = new Ratelimit({
-  redis: Redis.fromEnv(),
-  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
-});
+### Authentication Issues
+- Verify your `authenticateUser` function returns the correct format
+- Check that your authentication provider is working
+- Make sure JWT requests include authentication cookies/headers
 
-// In your API route
-export async function GET(request: NextRequest) {
-  // Rate limiting
-  const identifier = await getUserIdentifier(request); // IP or user ID
-  const { success } = await ratelimit.limit(identifier);
+### TypeScript Errors
+- All types are exported from the main package
+- Resource parameters are fully typed for access control hooks
+- Use the generated configuration template as a starting point
 
-  if (!success) {
-    return createErrorResponse('Too many requests', 429);
-  }
+## 📦 What's Included
 
-  // Your Vortex handler
-  return handleGetInvitationsByTarget(request);
-}
-```
+This SDK re-exports everything from `@teamvortexsoftware/vortex-node-22-sdk`, so you get:
 
-### Security Checklist
-- ✅ **Rate limiting**: Prevent DoS attacks
-- ✅ **Input validation**: All user input is sanitized by the SDK
-- ✅ **Error logging**: Log security events without exposing internals
-- ✅ **HTTPS only**: Never use these endpoints over HTTP
-- ✅ **Secret management**: Use proper secret storage (not `.env` files in production)
-- ✅ **Monitoring**: Monitor for unusual access patterns
+- ✅ `Vortex` class for direct API access
+- ✅ All invitation management methods
+- ✅ JWT generation utilities
+- ✅ TypeScript definitions
+- ✅ Next.js optimized route handlers
 
-## TypeScript Support
+## 🔗 Links
 
-This package includes full TypeScript definitions. All types from the underlying Node.js SDK are re-exported for convenience.
+- [Node.js SDK Documentation](../vortex-node-22-sdk/README.md)
+- [React Provider Documentation](../vortex-react-provider/README.md)
+- [Example Implementation](../../apps/demo-react)
 
-## Requirements
+---
 
-- Next.js 13.0.0 or higher
-- Node.js 18 or higher
+**Need help?** Open an issue or check the example implementation in `apps/demo-react`.