@nextsparkjs/theme-default 0.1.0-beta.28 → 0.1.0-beta.30

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NextSpark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/config/app.config.ts

@@ -91,78 +91,51 @@ export const APP_CONFIG_OVERRIDES = {
   // =============================================================================
   // DOCUMENTATION CONFIGURATION
   // =============================================================================
+  /**
+   * Documentation system configuration
+   *
+   * Structure:
+   * - public: User-facing documentation at /docs
+   * - superadmin: Admin documentation at /superadmin/docs
+   *
+   * NOTE: Plugin docs are NOT in the registry - they are for developer reference only (IDE/LLM).
+   */
   docs: {
-    /**
-     * Enable/disable documentation system
-     */
+    /** Enable/disable documentation system */
     enabled: true,
 
-    /**
-     * Public access to documentation
-     * - true: Documentation accessible without authentication
-     * - false: Requires user to be logged in
-     */
-    public: true,
+    /** Make public documentation accessible without authentication */
+    publicAccess: true,
 
-    /**
-     * Enable search functionality in documentation
-     */
+    /** Enable search functionality in documentation */
     searchEnabled: true,
 
-    /**
-     * Show breadcrumbs in documentation pages
-     */
+    /** Show breadcrumbs in documentation pages */
     breadcrumbs: true,
 
     /**
-     * Theme Documentation Configuration
-     * Controls how theme-level documentation appears in the sidebar
+     * Public Documentation Configuration
+     * Controls public-facing documentation at /docs routes
      */
-    theme: {
-      /** Show/hide theme documentation category */
+    public: {
+      /** Show/hide public documentation */
       enabled: true,
-      /** Expand theme category by default on page load */
+      /** Expand sections by default on page load */
       open: true,
-      /** Custom label displayed in sidebar for theme category */
-      label: "Default Theme",
+      /** Custom label displayed in sidebar */
+      label: "Documentation",
     },
 
     /**
-     * Plugins Documentation Configuration
-     * Controls how plugin documentation appears in the sidebar
+     * Superadmin Documentation Configuration
+     * Controls admin documentation at /superadmin/docs routes
      */
-    plugins: {
-      /** Show/hide plugin documentation category */
+    superadmin: {
+      /** Show/hide superadmin documentation */
       enabled: true,
-      /** Expand plugins category by default on page load */
-      open: false,
-      /** Custom label displayed in sidebar for plugins category */
-      label: "Plugins",
+      /** Custom label displayed in sidebar */
+      label: "Admin Docs",
     },
-
-    /**
-     * Core Documentation Configuration
-     * Controls how core framework documentation appears in the sidebar
-     */
-    core: {
-      /** Show/hide core documentation category */
-      enabled: true,
-      /** Expand core category by default on page load */
-      open: true,
-      /** Custom label displayed in sidebar for core category */
-      label: "Core",
-    },
-
-    /**
-     * Additional environment-based check for plugin docs in production
-     * Plugin docs will only show if BOTH conditions are met:
-     * 1. plugins.enabled is true
-     * 2. Either in development OR showPluginsDocsInProd is true
-     *
-     * @deprecated Prefer using plugins.enabled for simpler control
-     * By default plugins documentation is not available in prod environments
-     */
-    showPluginsDocsInProd: false,
   },
 
   // =============================================================================

package/docs/{01-overview → public/01-overview}/01-introduction.md

@@ -1,3 +1,8 @@
+---
+title: Introduction
+description: Overview of the Default Theme and its key features for NextSpark applications.
+---
+
 # Default Theme Introduction
 
 ## Overview

package/docs/{01-overview → public/01-overview}/02-customization.md

@@ -1,3 +1,8 @@
+---
+title: Customization
+description: Learn how to customize colors, typography, components, and functionality in the default theme.
+---
+
 # Theme Customization
 
 ## Introduction

package/docs/{02-features → public/02-features}/03-tasks-entity.md

@@ -1,3 +1,8 @@
+---
+title: Tasks Entity
+description: Complete guide to the Tasks entity implementation with CRUD operations, metadata, and API access.
+---
+
 # Tasks Entity
 
 ## Introduction

package/docs/{03-ai → public/03-ai}/01-overview.md

@@ -1,3 +1,8 @@
+---
+title: AI Assistant Overview
+description: Learn about the AI-powered assistant features and multi-agent architecture.
+---
+
 # AI Assistant - Overview
 
 This theme includes an AI-powered assistant that helps users manage tasks, customers, and pages through natural language.

package/docs/{03-ai → public/03-ai}/02-customization.md

@@ -1,3 +1,8 @@
+---
+title: AI Customization
+description: Guide to customizing and extending the AI assistant with custom tools and handlers.
+---
+
 # AI Assistant - Customization
 
 This guide covers how to customize and extend the AI assistant for your specific needs.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/theme-default",
-  "version": "0.1.0-beta.28",
+  "version": "0.1.0-beta.30",
   "private": false,
   "type": "module",
   "main": "./config/theme.config.ts",
@@ -9,7 +9,6 @@
   ],
   "dependencies": {},
   "peerDependencies": {
-    "@nextsparkjs/core": "0.1.0-beta.24",
     "@tanstack/react-query": "^5.0.0",
     "lucide-react": "^0.539.0",
     "next": "^15.0.0",
@@ -17,10 +16,11 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@nextsparkjs/core": "0.1.0-beta.30"
   },
   "nextspark": {
     "type": "theme",
     "name": "default"
   }
-}
+}

package/tests/cypress.config.ts

@@ -2,17 +2,17 @@
  * Cypress Configuration for Default Theme
  *
  * This config works in both monorepo and npm mode.
- * Run with: NEXT_PUBLIC_ACTIVE_THEME=default pnpm cy:open
+ * Run with: pnpm cy:open or pnpm cy:run
+ *
+ * Filter by tags: pnpm cy:tags "@smoke" or pnpm cy:run --env grepTags="@smoke"
  */
 
 import { defineConfig } from 'cypress'
 import path from 'path'
 import fs from 'fs'
-import { fileURLToPath } from 'url'
 
-// ESM-compatible __dirname
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
+// __dirname is available because ts-node processes this file as CommonJS
+// (Next.js projects don't use "type": "module" in package.json)
 
 // Paths relative to this config file
 const themeRoot = path.resolve(__dirname, '..')