@nextsparkjs/theme-default 0.1.0-beta.44 → 0.1.0-beta.45

package/components/ai-chat/ChatPanel.tsx

@@ -8,7 +8,7 @@ import { MessageInput } from './MessageInput'
 import { MarkdownRenderer } from './MarkdownRenderer'
 import { TypingIndicator } from './TypingIndicator'
 import { ConversationSidebar } from './ConversationSidebar'
-import { createCyId } from '@nextsparkjs/testing/utils'
+import { sel } from '@nextsparkjs/core/selectors'
 import { cn } from '@nextsparkjs/core/lib/utils'
 import { Bot, User, Loader2, Trash2, ListTodo, Users, FileText, Sparkles, X } from 'lucide-react'
 import type { ConversationInfo } from '../../lib/hooks/useConversations'
@@ -163,7 +163,7 @@ function ChatMessageItem({
 
     return (
         <div
-            data-cy={createCyId(cyPrefix, `message-${message.role}`)}
+            data-cy={sel(message.role === 'user' ? 'common.aiChat.messageUser' : 'common.aiChat.messageAssistant')}
             className={cn(
                 'flex w-full gap-3 p-4',
                 isUser ? 'flex-row-reverse' : 'flex-row'
@@ -351,7 +351,7 @@ export function ChatPanel({
     return (
         <div className="h-[calc(100vh-4rem)] p-4 md:p-6 lg:p-8">
             <Card
-                data-cy={createCyId(cyPrefix, 'panel')}
+                data-cy={sel('common.aiChat.panel')}
                 className={cn(
                     'flex h-full mx-auto overflow-hidden shadow-lg',
                     layoutClass
@@ -408,7 +408,7 @@ export function ChatPanel({
                                 {/* Clear button */}
                                 {header.showClearButton && header.onClear && (
                                     <Button
-                                        data-cy={createCyId(cyPrefix, 'clear-btn')}
+                                        data-cy={sel('common.aiChat.clearBtn')}
                                         variant="ghost"
                                         size="sm"
                                         onClick={header.onClear}
@@ -470,13 +470,13 @@ export function ChatPanel({
                     ) : (
                         /* Messages */
                         <ScrollArea
-                            data-cy={createCyId(cyPrefix, 'message-list')}
+                            data-cy={sel('common.aiChat.messageList')}
                             className="flex-1 p-4"
                         >
                             <div className="flex flex-col gap-4">
                                 {error && (
                                     <div
-                                        data-cy={createCyId(cyPrefix, 'error-message')}
+                                        data-cy={sel('common.aiChat.errorMessage')}
                                         className="p-4 mb-2 text-sm text-red-600 bg-red-50 dark:bg-red-900/20 dark:text-red-400 rounded-lg"
                                     >
                                         {error}
@@ -517,7 +517,7 @@ export function ChatPanel({
                                             variant="outline"
                                             size="sm"
                                             onClick={onCancelStream}
-                                            data-cy="chat-cancel-button"
+                                            data-cy={sel('common.aiChat.cancelBtn')}
                                         >
                                             <X className="h-4 w-4 mr-1" />
                                             Stop generating

package/components/ai-chat/Message.tsx

@@ -2,7 +2,7 @@ import { cn } from '@nextsparkjs/core/lib/utils'
 import { Message as MessageType } from '../../lib/hooks/useAiChat'
 import { MarkdownRenderer } from './MarkdownRenderer'
 import { User, Bot } from 'lucide-react'
-import { createCyId } from '@nextsparkjs/testing/utils'
+import { sel } from '@nextsparkjs/core/selectors'
 
 interface MessageProps {
     message: MessageType
@@ -13,7 +13,7 @@ export function Message({ message }: MessageProps) {
 
     return (
         <div
-            data-cy={createCyId('ai-chat', `message-${message.role}`)}
+            data-cy={sel(message.role === 'user' ? 'common.aiChat.messageUser' : 'common.aiChat.messageAssistant')}
             className={cn(
                 'flex w-full gap-3 p-4',
                 isUser ? 'flex-row-reverse' : 'flex-row'

package/components/ai-chat/MessageInput.tsx

@@ -2,7 +2,7 @@ import { KeyboardEvent } from 'react'
 import { Button } from '@nextsparkjs/core/components/ui/button'
 import { Textarea } from '@nextsparkjs/core/components/ui/textarea'
 import { Send } from 'lucide-react'
-import { createCyId } from '@nextsparkjs/testing/utils'
+import { sel } from '@nextsparkjs/core/selectors'
 
 interface MessageInputProps {
     value: string
@@ -23,7 +23,7 @@ export function MessageInput({ value, onChange, onSend, isLoading }: MessageInpu
         <div className="p-4 border-t bg-background">
             <div className="flex gap-2">
                 <Textarea
-                    data-cy={createCyId('ai-chat', 'message-input')}
+                    data-cy={sel('common.aiChat.messageInput')}
                     value={value}
                     onChange={(e) => onChange(e.target.value)}
                     onKeyDown={handleKeyDown}
@@ -32,7 +32,7 @@ export function MessageInput({ value, onChange, onSend, isLoading }: MessageInpu
                     disabled={isLoading}
                 />
                 <Button
-                    data-cy={createCyId('ai-chat', 'send-btn')}
+                    data-cy={sel('common.aiChat.sendBtn')}
                     size="icon"
                     onClick={onSend}
                     disabled={!value.trim() || isLoading}

package/components/ai-chat/MessageList.tsx

@@ -3,7 +3,7 @@ import { ScrollArea } from '@nextsparkjs/core/components/ui/scroll-area'
 import { Message as MessageType } from '../../lib/hooks/useAiChat'
 import { Message } from './Message'
 import { TypingIndicator } from './TypingIndicator'
-import { createCyId } from '@nextsparkjs/testing/utils'
+import { sel } from '@nextsparkjs/core/selectors'
 
 interface MessageListProps {
     messages: MessageType[]
@@ -21,11 +21,11 @@ export function MessageList({ messages, isLoading, error }: MessageListProps) {
     }, [messages, isLoading])
 
     return (
-        <ScrollArea data-cy={createCyId('ai-chat', 'message-list')} className="flex-1 p-4">
+        <ScrollArea data-cy={sel('common.aiChat.messageList')} className="flex-1 p-4">
             <div className="flex flex-col gap-4">
                 {error && (
                     <div
-                        data-cy={createCyId('ai-chat', 'error-message')}
+                        data-cy={sel('common.aiChat.errorMessage')}
                         className="p-4 mb-2 text-sm text-red-600 bg-red-50 dark:bg-red-900/20 dark:text-red-400 rounded-lg"
                     >
                         {error}

package/components/ai-chat/TypingIndicator.tsx

@@ -1,8 +1,8 @@
-import { createCyId } from '@nextsparkjs/testing/utils'
+import { sel } from '@nextsparkjs/core/selectors'
 
 export function TypingIndicator() {
     return (
-        <div data-cy={createCyId('ai-chat', 'typing-indicator')} className="flex items-center gap-1 p-2">
+        <div data-cy={sel('common.aiChat.typingIndicator')} className="flex items-center gap-1 p-2">
             <div className="w-2 h-2 bg-muted-foreground/40 rounded-full animate-bounce [animation-delay:-0.3s]" />
             <div className="w-2 h-2 bg-muted-foreground/40 rounded-full animate-bounce [animation-delay:-0.15s]" />
             <div className="w-2 h-2 bg-muted-foreground/40 rounded-full animate-bounce" />

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 |

package/entities/pages/api/presets.ts

@@ -0,0 +1,72 @@
+/**
+ * API Presets for Pages Entity
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * The endpoint is automatically derived from the entity name: /api/v1/pages
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage builder-enabled pages',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Pages',
+      description: 'Fetch all pages with default pagination',
+      method: 'GET',
+      params: {
+        limit: 10,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-published',
+      title: 'List Published Pages',
+      description: 'Fetch only published pages',
+      method: 'GET',
+      params: {
+        status: 'published',
+        limit: 20
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-locale',
+      title: 'List Spanish Pages',
+      description: 'Fetch pages in Spanish locale',
+      method: 'GET',
+      params: {
+        locale: 'es',
+        limit: 10
+      },
+      tags: ['read', 'filter', 'i18n']
+    },
+    {
+      id: 'create-draft',
+      title: 'Create Draft Page',
+      description: 'Create a new page as draft',
+      method: 'POST',
+      payload: {
+        title: 'New Page',
+        slug: 'new-page',
+        status: 'draft',
+        locale: 'en',
+        blocks: []
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'search-title',
+      title: 'Search by Title',
+      description: 'Search pages by title',
+      method: 'GET',
+      params: {
+        search: 'About',
+        searchField: 'title'
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})

package/entities/posts/api/docs.md

@@ -0,0 +1,120 @@
+# Posts API
+
+Manage blog posts with builder support and taxonomies. Posts render at /blog/[slug] and support categories, featured images, and excerpts.
+
+## Overview
+
+The Posts API allows you to create, read, update, and delete blog posts with builder content. Posts support the page builder for content creation and include taxonomy management for categories.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Posts
+`GET /api/v1/posts`
+
+Returns a paginated list of posts.
+
+**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)
+- `search` (string, optional): Search term for title/excerpt
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "post_123",
+      "title": "Getting Started with NextSpark",
+      "slug": "getting-started",
+      "status": "published",
+      "excerpt": "Learn how to build amazing apps with NextSpark",
+      "featuredImage": "/uploads/hero.jpg",
+      "blocks": [...],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Post
+`GET /api/v1/posts/[id]`
+
+Returns a single post by ID.
+
+**Path Parameters:**
+- `id` (string, required): Post ID
+
+### Create Post
+`POST /api/v1/posts`
+
+Create a new post record.
+
+**Request Body:**
+```json
+{
+  "title": "My New Blog Post",
+  "slug": "my-new-blog-post",
+  "status": "draft",
+  "excerpt": "A brief introduction to my post",
+  "blocks": []
+}
+```
+
+### Update Post
+`PATCH /api/v1/posts/[id]`
+
+Update an existing post.
+
+**Path Parameters:**
+- `id` (string, required): Post ID
+
+**Request Body:**
+Any fields to update (partial update supported).
+
+### Delete Post
+`DELETE /api/v1/posts/[id]`
+
+Delete a post record.
+
+**Path Parameters:**
+- `id` (string, required): Post ID
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | text | Yes | Post title |
+| slug | text | Yes | URL-friendly identifier |
+| status | select | Yes | draft, published, scheduled, archived |
+| excerpt | textarea | No | Short summary of the post |
+| featuredImage | image | No | Main image for the post |
+| blocks | json | No | Page builder content |
+
+## Taxonomies
+
+Posts support the following taxonomies:
+- **categories** (post_category): Multiple categories can be assigned
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Post doesn't exist |
+| 422 | Validation Error - Invalid data |