@nextsparkjs/theme-default 0.1.0-beta.1 → 0.1.0-beta.101

package/docs/superadmin/01-setup/01-configuration.md

@@ -0,0 +1,79 @@
+---
+title: Configuration
+description: Environment variables and configuration options for NextSpark applications.
+---
+
+# Configuration Guide
+
+This guide covers the configuration options available to administrators for setting up and customizing your NextSpark application.
+
+## Environment Variables
+
+### Required Variables
+
+```bash
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+
+# Authentication
+BETTER_AUTH_SECRET="your-secret-key"
+
+# Application
+NEXT_PUBLIC_APP_URL="https://your-domain.com"
+```
+
+### Optional Variables
+
+```bash
+# Email (for notifications)
+SMTP_HOST="smtp.example.com"
+SMTP_PORT="587"
+SMTP_USER="user@example.com"
+SMTP_PASSWORD="password"
+
+# Billing (Stripe)
+STRIPE_SECRET_KEY="sk_..."
+STRIPE_WEBHOOK_SECRET="whsec_..."
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_..."
+```
+
+## Configuration Files
+
+### app.config.ts
+
+The main application configuration file located at `config/app.config.ts`:
+
+```typescript
+export const APP_CONFIG_OVERRIDES = {
+  app: {
+    name: 'Your App Name',
+    version: '1.0.0',
+  },
+  teams: {
+    mode: 'multi-tenant', // or 'single-tenant', 'single-user'
+  },
+  i18n: {
+    supportedLocales: ['en', 'es'],
+    defaultLocale: 'en',
+  },
+}
+```
+
+### permissions.config.ts
+
+Define roles and permissions in `config/permissions.config.ts`:
+
+```typescript
+export const PERMISSIONS_CONFIG = {
+  roles: {
+    additionalRoles: ['editor'],
+    hierarchy: { editor: 5 },
+  },
+  // ... permissions
+}
+```
+
+## Next Steps
+
+- [Deployment Guide](./02-deployment.md)
+- [User Management](../02-management/01-users.md)

package/docs/superadmin/01-setup/02-deployment.md

@@ -0,0 +1,82 @@
+---
+title: Deployment
+description: Guide to deploying NextSpark applications to Vercel, Docker, and other platforms.
+---
+
+# Deployment Guide
+
+This guide covers deploying your NextSpark application to production environments.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- PostgreSQL database provisioned
+- Domain configured with SSL
+
+## Vercel Deployment
+
+### 1. Connect Repository
+
+1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
+2. Click "Add New Project"
+3. Import your Git repository
+
+### 2. Configure Environment Variables
+
+Add all required environment variables in Vercel project settings:
+
+```
+DATABASE_URL=postgresql://...
+BETTER_AUTH_SECRET=...
+NEXT_PUBLIC_APP_URL=https://your-domain.com
+```
+
+### 3. Deploy
+
+Vercel will automatically build and deploy your application.
+
+## Docker Deployment
+
+### Build Image
+
+```bash
+docker build -t nextspark-app .
+```
+
+### Run Container
+
+```bash
+docker run -p 3000:3000 \
+  -e DATABASE_URL="postgresql://..." \
+  -e BETTER_AUTH_SECRET="..." \
+  nextspark-app
+```
+
+## Database Migrations
+
+Run migrations before starting the application:
+
+```bash
+pnpm db:migrate
+```
+
+## Health Checks
+
+The application exposes health check endpoints:
+
+- `/api/health` - Basic health check
+- `/api/health/db` - Database connectivity check
+
+## Monitoring
+
+Configure monitoring and alerting for:
+
+- Application errors
+- Database connection issues
+- API response times
+- Memory and CPU usage
+
+## Next Steps
+
+- [Configuration Guide](./01-configuration.md)
+- [User Management](../02-management/01-users.md)

package/docs/superadmin/02-management/01-users.md

@@ -0,0 +1,83 @@
+---
+title: User Management
+description: Managing users, teams, and roles in your NextSpark application.
+---
+
+# User Management
+
+This guide covers managing users and teams in your NextSpark application.
+
+## User Roles
+
+### System Roles
+
+| Role | Description |
+|------|-------------|
+| `superadmin` | Full system access, can manage all users and teams |
+| `developer` | Access to developer tools and debugging features |
+| `member` | Standard user role |
+
+### Team Roles
+
+| Role | Description |
+|------|-------------|
+| `owner` | Team creator, full team management |
+| `admin` | Can manage team settings and members |
+| `member` | Standard team member |
+| `viewer` | Read-only access |
+
+## Managing Users
+
+### View All Users
+
+Access the user management panel at `/superadmin/users`:
+
+1. Navigate to Superadmin Dashboard
+2. Click on "Users" in the sidebar
+3. Use filters to search by name, email, or role
+
+### Update User Role
+
+1. Find the user in the list
+2. Click on the user row to open details
+3. Select new role from dropdown
+4. Click "Save Changes"
+
+### Deactivate User
+
+1. Open user details
+2. Click "Deactivate Account"
+3. Confirm the action
+
+## Managing Teams
+
+### View All Teams
+
+Access team management at `/superadmin/teams`:
+
+- See all teams across the platform
+- View team member counts
+- Monitor team activity
+
+### Team Impersonation
+
+Superadmins can view the application as any team member:
+
+1. Navigate to team details
+2. Click "Impersonate" on a team member
+3. You'll see the app from their perspective
+4. Click "Exit Impersonation" when done
+
+## Audit Logs
+
+All administrative actions are logged. View logs at `/superadmin/logs`:
+
+- User creation/deletion
+- Role changes
+- Team modifications
+- Login attempts
+
+## Next Steps
+
+- [Configuration Guide](../01-setup/01-configuration.md)
+- [Deployment Guide](../01-setup/02-deployment.md)

package/docs/superadmin/03-integrations/01-langchain.md

@@ -0,0 +1,139 @@
+---
+title: Langchain Integration
+description: Configure and manage the AI-powered Langchain plugin for your application.
+---
+
+# Langchain Integration
+
+The Langchain plugin provides AI-powered capabilities to your application, including conversational agents, document processing, and intelligent automation.
+
+## Overview
+
+Langchain is integrated as a plugin that can be enabled per-theme. It provides:
+
+- **Conversational AI**: Build chat interfaces with context-aware responses
+- **Memory Management**: Persistent conversation history with PostgreSQL storage
+- **Tool Integration**: Connect AI to your application's data and actions
+- **Streaming Responses**: Real-time AI responses for better UX
+
+## Configuration
+
+### Environment Variables
+
+Add the following to your `.env` file:
+
+```bash
+# OpenAI API Key (required)
+OPENAI_API_KEY=sk-your-api-key-here
+
+# Optional: Model configuration
+LANGCHAIN_MODEL=gpt-4o-mini
+LANGCHAIN_TEMPERATURE=0.7
+LANGCHAIN_MAX_TOKENS=2000
+```
+
+### Plugin Activation
+
+Enable the plugin in your theme configuration:
+
+```typescript
+// themes/{theme}/config/theme.config.ts
+export const themeConfig = {
+  plugins: ['langchain'],
+  // ...
+}
+```
+
+## Database Setup
+
+The plugin requires a memory table for conversation persistence. Run the migration:
+
+```bash
+pnpm db:migrate
+```
+
+This creates the `langchain_memory` table with the following schema:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | uuid | Primary key |
+| sessionId | varchar | Conversation session identifier |
+| messages | jsonb | Array of message objects |
+| metadata | jsonb | Additional context data |
+| createdAt | timestamp | Creation timestamp |
+| updatedAt | timestamp | Last update timestamp |
+
+## Usage
+
+### Basic Chat Endpoint
+
+The plugin exposes an API endpoint for chat interactions:
+
+```typescript
+// POST /api/v1/ai/chat
+{
+  "message": "Hello, how can you help me?",
+  "sessionId": "user-123-session-456"
+}
+```
+
+Response:
+
+```typescript
+{
+  "success": true,
+  "data": {
+    "response": "Hello! I'm here to help you with...",
+    "sessionId": "user-123-session-456"
+  }
+}
+```
+
+### Streaming Responses
+
+For real-time streaming:
+
+```typescript
+// POST /api/v1/ai/chat/stream
+{
+  "message": "Explain quantum computing",
+  "sessionId": "user-123-session-456",
+  "stream": true
+}
+```
+
+## Security Considerations
+
+- **API Key Protection**: Never expose your OpenAI API key in client-side code
+- **Rate Limiting**: Consider implementing rate limits per user/team
+- **Content Filtering**: The plugin includes basic content moderation
+- **Session Isolation**: Conversations are isolated by sessionId
+
+## Monitoring
+
+View AI usage statistics in the Superadmin dashboard:
+
+1. Navigate to **Superadmin > Analytics** (coming soon)
+2. Select the **AI Usage** tab
+3. Monitor token usage, response times, and error rates
+
+## Troubleshooting
+
+### Common Issues
+
+**"OPENAI_API_KEY not configured"**
+- Ensure the environment variable is set
+- Restart the development server after adding the key
+
+**"Rate limit exceeded"**
+- OpenAI has per-minute and per-day limits
+- Consider implementing request queuing
+
+**"Memory not persisting"**
+- Verify the database migration ran successfully
+- Check that `sessionId` is being passed consistently
+
+## Related Documentation
+
+- [Plugin System](/docs/plugins/overview)
+- [API Authentication](/docs/api/authentication)

package/entities/customers/api/docs.md

@@ -0,0 +1,107 @@
+# Customers API
+
+Manage customer records in the system. This endpoint supports full CRUD operations with team-based multi-tenancy.
+
+## Overview
+
+The Customers API allows you to create, read, update, and delete customer records. Each customer belongs to a team and is automatically filtered based on the authenticated user's team context.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Customers
+`GET /api/v1/customers`
+
+Returns a paginated list of customers for the current team.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (active, inactive, pending)
+- `search` (string, optional): Search term for partial matching
+- `searchField` (string, optional): Field to search in (name, email)
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "cust_123",
+      "name": "John Doe",
+      "email": "john@example.com",
+      "status": "active",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Customer
+`GET /api/v1/customers/[id]`
+
+Returns a single customer by ID.
+
+**Path Parameters:**
+- `id` (string, required): Customer ID
+
+### Create Customer
+`POST /api/v1/customers`
+
+Create a new customer record.
+
+**Request Body:**
+```json
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "phone": "+1234567890",
+  "status": "active"
+}
+```
+
+### Update Customer
+`PATCH /api/v1/customers/[id]`
+
+Update an existing customer.
+
+**Path Parameters:**
+- `id` (string, required): Customer ID
+
+**Request Body:**
+Any fields to update (partial update supported).
+
+### Delete Customer
+`DELETE /api/v1/customers/[id]`
+
+Delete a customer record.
+
+**Path Parameters:**
+- `id` (string, required): Customer ID
+
+## Admin Bypass
+
+Superadmin users can access customers across all teams by sending:
+- Header: `x-admin-bypass: confirm-cross-team-access`
+- Optional header: `x-team-id: {team_id}` to filter a specific team
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Customer doesn't exist |
+| 422 | Validation Error - Invalid data |

package/entities/customers/api/presets.ts

@@ -0,0 +1,80 @@
+/**
+ * API Presets for Customers Entity
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * The endpoint is automatically derived from the entity name: /api/v1/customers
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  // endpoint is optional - derived from entity folder name
+  summary: 'Manage customer records in the system',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Customers',
+      description: 'Fetch all customers with default pagination',
+      method: 'GET',
+      params: {
+        limit: 10,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-by-status',
+      title: 'List Active Customers',
+      description: 'Fetch only customers with active status',
+      method: 'GET',
+      params: {
+        status: 'active',
+        limit: 20
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'create-test',
+      title: 'Create Test Customer',
+      description: 'Create a new customer with sample data for testing',
+      method: 'POST',
+      payload: {
+        name: 'Test Customer',
+        email: 'test@example.com',
+        phone: '+1234567890',
+        status: 'active'
+      },
+      sessionConfig: {
+        crossTeam: false
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'create-bypass',
+      title: 'Create (Bypass Mode)',
+      description: 'Create customer using admin bypass for cross-team access',
+      method: 'POST',
+      payload: {
+        name: 'Cross-Team Customer',
+        email: 'crossteam@example.com',
+        status: 'pending'
+      },
+      sessionConfig: {
+        crossTeam: true,
+        teamId: '{{FIRST_TEAM_ID}}'
+      },
+      tags: ['write', 'admin', 'bypass']
+    },
+    {
+      id: 'search-name',
+      title: 'Search by Name',
+      description: 'Search customers by name using partial match',
+      method: 'GET',
+      params: {
+        search: 'John',
+        searchField: 'name'
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})

package/entities/pages/api/docs.md

@@ -0,0 +1,114 @@
+# Pages API
+
+Manage builder-enabled pages in the system. Pages render at root URLs (e.g., /about, /contact) and support the page builder for content creation.
+
+## Overview
+
+The Pages API allows you to create, read, update, and delete pages with builder content. Pages are public content and can be accessed by all authenticated users.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Pages
+`GET /api/v1/pages`
+
+Returns a paginated list of pages.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (draft, published, scheduled, archived)
+- `locale` (string, optional): Filter by locale (en, es)
+- `search` (string, optional): Search term for title/slug
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "page_123",
+      "title": "About Us",
+      "slug": "about",
+      "status": "published",
+      "locale": "en",
+      "blocks": [...],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 15,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Page
+`GET /api/v1/pages/[id]`
+
+Returns a single page by ID.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+### Create Page
+`POST /api/v1/pages`
+
+Create a new page record.
+
+**Request Body:**
+```json
+{
+  "title": "Contact Us",
+  "slug": "contact",
+  "status": "draft",
+  "locale": "en",
+  "blocks": []
+}
+```
+
+### Update Page
+`PATCH /api/v1/pages/[id]`
+
+Update an existing page.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+**Request Body:**
+Any fields to update (partial update supported).
+
+### Delete Page
+`DELETE /api/v1/pages/[id]`
+
+Delete a page record.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | text | Yes | Page title |
+| slug | text | Yes | URL-friendly identifier |
+| status | select | Yes | draft, published, scheduled, archived |
+| locale | select | Yes | en, es |
+| blocks | json | No | Page builder content |
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Page doesn't exist |
+| 422 | Validation Error - Invalid data |