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

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/api/authors/[username]/route.ts

@@ -9,6 +9,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 interface Author {
   id: string
@@ -39,10 +40,10 @@ interface RouteContext {
   }>
 }
 
-export async function GET(
+const getHandler = async (
   request: NextRequest,
   context: RouteContext
-) {
+) => {
   try {
     const { username } = await context.params
 
@@ -148,3 +149,5 @@ export async function GET(
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/api/authors/docs.md

@@ -0,0 +1,135 @@
+# Authors API
+
+Public author profiles and post listings. No authentication required.
+
+## Overview
+
+The Authors API provides read-only access to author profiles and their published posts. This endpoint is designed for public consumption and does not require authentication.
+
+## Authentication
+
+**No authentication required** - This is a public endpoint.
+
+## Endpoints
+
+### List Authors
+`GET /api/v1/theme/blog/authors`
+
+Returns a list of all authors who have published posts.
+
+**Example Request:**
+```bash
+curl https://example.com/api/v1/theme/blog/authors
+```
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "user_abc123",
+      "name": "John Doe",
+      "username": "johndoe",
+      "bio": "Full-stack developer and tech writer",
+      "image": "https://example.com/avatar.jpg",
+      "postCount": 15
+    },
+    {
+      "id": "user_def456",
+      "name": "Jane Smith",
+      "username": "janesmith",
+      "bio": "Product designer and UX enthusiast",
+      "image": "https://example.com/avatar2.jpg",
+      "postCount": 8
+    }
+  ]
+}
+```
+
+### Get Author Profile
+`GET /api/v1/theme/blog/authors/[username]`
+
+Returns an author's profile with their published posts.
+
+**Path Parameters:**
+- `username` (string, required): Author's username
+
+**Example Request:**
+```bash
+curl https://example.com/api/v1/theme/blog/authors/johndoe
+```
+
+**Example Response:**
+```json
+{
+  "author": {
+    "id": "user_abc123",
+    "name": "John Doe",
+    "username": "johndoe",
+    "bio": "Full-stack developer and tech writer",
+    "image": "https://example.com/avatar.jpg"
+  },
+  "posts": [
+    {
+      "id": "post_123",
+      "title": "Getting Started with Next.js",
+      "slug": "getting-started-with-nextjs",
+      "excerpt": "A comprehensive guide...",
+      "featuredImage": "https://example.com/image.jpg",
+      "publishedAt": "2024-01-15T10:30:00Z",
+      "categories": [
+        {
+          "id": "cat_123",
+          "name": "Technology",
+          "slug": "technology"
+        }
+      ]
+    }
+  ],
+  "stats": {
+    "totalPosts": 15
+  }
+}
+```
+
+## Response Fields
+
+### Author Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Author user ID |
+| name | string | Author display name |
+| username | string | Author username (URL-friendly) |
+| bio | string | Author biography |
+| image | string | Author avatar URL |
+| postCount | number | Number of published posts (list endpoint only) |
+
+### Author Profile Response
+
+| Field | Type | Description |
+|-------|------|-------------|
+| author | object | Author profile information |
+| posts | array | Array of published posts |
+| stats.totalPosts | number | Total number of published posts |
+
+## Features
+
+- **No Auth Required**: Accessible without authentication
+- **Rate Limited**: 100 requests per minute per IP
+- **Cached**: Responses cached for 60 seconds
+- **Sorted by Post Count**: Authors with more posts appear first
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 404 | Not Found - Author not found |
+| 429 | Too Many Requests - Rate limit exceeded |
+| 500 | Internal Server Error |
+
+## Related APIs
+
+- **[Public Posts](/api/v1/theme/blog/posts/public)** - Public post feed
+- **[Posts](/api/v1/posts)** - Authenticated CRUD operations

package/api/authors/presets.ts

@@ -0,0 +1,45 @@
+/**
+ * API Presets for Authors Route
+ *
+ * Public author profiles and their published posts
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/theme/blog/authors',
+  summary: 'Public author profiles with published posts',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Authors',
+      description: 'Get all authors with published posts',
+      method: 'GET',
+      params: {
+        limit: 50
+      },
+      tags: ['read', 'list', 'public']
+    },
+    {
+      id: 'get-by-username',
+      title: 'Get Author by Username',
+      description: 'Get author profile with their posts',
+      method: 'GET',
+      pathParams: {
+        username: '{{username}}'
+      },
+      tags: ['read', 'detail', 'public']
+    },
+    {
+      id: 'list-with-post-count',
+      title: 'List with Post Count',
+      description: 'Get authors sorted by number of posts',
+      method: 'GET',
+      params: {
+        sortBy: 'postCount',
+        sortOrder: 'desc'
+      },
+      tags: ['read', 'list', 'public']
+    }
+  ]
+})

package/api/authors/route.ts

@@ -9,6 +9,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 interface AuthorWithCount {
   id: string
@@ -19,7 +20,7 @@ interface AuthorWithCount {
   postCount: number
 }
 
-export async function GET(request: NextRequest) {
+const getHandler = async (request: NextRequest) => {
   try {
     // Get all authors who have at least one published post
     const authorsQuery = `
@@ -61,3 +62,5 @@ export async function GET(request: NextRequest) {
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/api/posts/public/docs.md

@@ -0,0 +1,124 @@
+# Public Posts API
+
+Public feed of published blog posts. No authentication required.
+
+## Overview
+
+The Public Posts API provides read-only access to published blog posts. This endpoint is designed for public consumption by blog visitors and does not require authentication.
+
+## Authentication
+
+**No authentication required** - This is a public endpoint.
+
+## Endpoints
+
+### List Published Posts
+`GET /api/v1/theme/blog/posts/public`
+
+Returns a paginated list of published posts.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20, Max: 100
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `category` (string, optional): Filter by category slug
+
+**Example Request:**
+```bash
+curl https://example.com/api/v1/theme/blog/posts/public?limit=10&category=technology
+```
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "post_abc123",
+      "title": "Getting Started with Next.js",
+      "slug": "getting-started-with-nextjs",
+      "excerpt": "A comprehensive guide to building modern web apps",
+      "featuredImage": "https://example.com/image.jpg",
+      "featured": true,
+      "publishedAt": "2024-01-15T10:30:00Z",
+      "author": {
+        "id": "user_123",
+        "name": "John Doe",
+        "username": "johndoe",
+        "image": "https://example.com/avatar.jpg"
+      },
+      "categories": [
+        {
+          "id": "cat_123",
+          "name": "Technology",
+          "slug": "technology"
+        }
+      ]
+    }
+  ],
+  "pagination": {
+    "total": 25,
+    "limit": 10,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+## Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Post unique identifier |
+| title | string | Post title |
+| slug | string | URL-friendly slug |
+| excerpt | string | Brief description |
+| featuredImage | string | Featured image URL |
+| featured | boolean | Whether post is featured |
+| publishedAt | datetime | Publication timestamp |
+| author | object | Author information |
+| author.id | string | Author user ID |
+| author.name | string | Author display name |
+| author.username | string | Author username |
+| author.image | string | Author avatar URL |
+| categories | array | Associated categories |
+
+## Features
+
+- **No Auth Required**: Accessible without authentication
+- **Rate Limited**: 100 requests per minute per IP
+- **Cached**: Responses cached for 60 seconds
+- **Category Filter**: Filter posts by category slug
+
+## Pagination
+
+The API uses offset-based pagination:
+
+```json
+{
+  "pagination": {
+    "total": 100,
+    "limit": 20,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+To get the next page:
+```
+GET /api/v1/theme/blog/posts/public?offset=20&limit=20
+```
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid query parameters |
+| 404 | Not Found - Category not found |
+| 429 | Too Many Requests - Rate limit exceeded |
+| 500 | Internal Server Error |
+
+## Related APIs
+
+- **[Posts](/api/v1/posts)** - Authenticated CRUD operations
+- **[Authors](/api/v1/theme/blog/authors)** - Author profiles
+- **[Categories](/api/v1/categories)** - Category management

package/api/posts/public/presets.ts

@@ -0,0 +1,65 @@
+/**
+ * API Presets for Public Posts
+ *
+ * Public feed of published blog posts (no authentication required)
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/theme/blog/posts/public',
+  summary: 'Public feed of published blog posts',
+  presets: [
+    {
+      id: 'list-recent',
+      title: 'List Recent Posts',
+      description: 'Get recent published posts',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list', 'public']
+    },
+    {
+      id: 'list-with-limit',
+      title: 'List with Custom Limit',
+      description: 'Get posts with specific limit',
+      method: 'GET',
+      params: {
+        limit: '{{limit}}'
+      },
+      tags: ['read', 'list', 'public']
+    },
+    {
+      id: 'list-by-category',
+      title: 'List by Category',
+      description: 'Get posts filtered by category slug',
+      method: 'GET',
+      params: {
+        category: '{{category}}'
+      },
+      tags: ['read', 'filter', 'public']
+    },
+    {
+      id: 'list-paginated',
+      title: 'List Paginated',
+      description: 'Get paginated posts',
+      method: 'GET',
+      params: {
+        limit: '{{limit}}',
+        offset: '{{offset}}'
+      },
+      tags: ['read', 'list', 'public']
+    },
+    {
+      id: 'list-featured',
+      title: 'List Featured Posts',
+      description: 'Get featured published posts',
+      method: 'GET',
+      params: {
+        featured: 'true'
+      },
+      tags: ['read', 'filter', 'public']
+    }
+  ]
+})

package/api/posts/public/route.ts

@@ -10,6 +10,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 interface Post {
   id: string
@@ -31,7 +32,7 @@ interface Post {
   authorImage: string | null
 }
 
-export async function GET(request: NextRequest) {
+const getHandler = async (request: NextRequest) => {
   try {
     const { searchParams } = new URL(request.url)
 
@@ -149,3 +150,5 @@ export async function GET(request: NextRequest) {
     )
   }
 }
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/config/app.config.ts

@@ -86,11 +86,10 @@ export const APP_CONFIG_OVERRIDES = {
   // =============================================================================
   api: {
     cors: {
-      allowedOrigins: {
-        development: [
-          'http://localhost:3000',
-          'http://localhost:5173',
-        ],
+      // Theme-specific CORS origins (extends core defaults, does not replace)
+      // No additional origins needed for blog theme - uses core defaults
+      additionalOrigins: {
+        development: [],
         production: [],
       },
     },

package/config/dashboard.config.ts

@@ -48,6 +48,19 @@ export const DASHBOARD_CONFIG = {
     devtoolsAccess: {
       enabled: true,
     },
+    /**
+     * Settings menu dropdown (gear icon)
+     */
+    settingsMenu: {
+      enabled: true,
+      links: [
+        {
+          label: 'navigation.patterns',
+          href: '/dashboard/patterns',
+          icon: 'layers',
+        },
+      ],
+    },
     userMenu: {
       enabled: true,
       showAvatar: true,

package/config/permissions.config.ts

@@ -48,6 +48,17 @@ export const PERMISSIONS_CONFIG_OVERRIDES: ThemePermissionsConfig = {
       { action: 'update', label: 'Edit categories', description: 'Can modify category information', roles: ['owner'] },
       { action: 'delete', label: 'Delete categories', description: 'Can delete categories', roles: ['owner'], dangerous: true },
     ],
+
+    // ------------------------------------------
+    // PATTERNS
+    // ------------------------------------------
+    patterns: [
+      { action: 'create', label: 'Create Patterns', description: 'Can create reusable patterns', roles: ['owner'] },
+      { action: 'read', label: 'View Patterns', description: 'Can view pattern details', roles: ['owner'] },
+      { action: 'list', label: 'List Patterns', description: 'Can see the patterns list', roles: ['owner'] },
+      { action: 'update', label: 'Edit Patterns', description: 'Can modify patterns', roles: ['owner'] },
+      { action: 'delete', label: 'Delete Patterns', description: 'Can delete patterns', roles: ['owner'], dangerous: true },
+    ],
   },
 
   // ==========================================

package/entities/categories/api/docs.md

@@ -0,0 +1,119 @@
+# Categories API
+
+Manage blog categories for organizing and filtering posts.
+
+## Overview
+
+The Categories API allows you to create, read, update, and delete category records. Categories provide a hierarchical organization system for blog posts through a many-to-many relationship.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Categories
+`GET /api/v1/categories`
+
+Returns a paginated list of categories.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `search` (string, optional): Search by name, description
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "category_abc123",
+      "name": "Technology",
+      "slug": "technology",
+      "description": "Posts about tech and software development",
+      "createdAt": "2024-01-15T10:30:00Z",
+      "updatedAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 8,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Category
+`GET /api/v1/categories/[id]`
+
+Returns a single category by ID.
+
+### Create Category
+`POST /api/v1/categories`
+
+Create a new category.
+
+**Request Body:**
+```json
+{
+  "name": "Technology",
+  "slug": "technology",
+  "description": "Posts about tech and software development"
+}
+```
+
+### Update Category
+`PATCH /api/v1/categories/[id]`
+
+Update an existing category. Supports partial updates.
+
+### Delete Category
+`DELETE /api/v1/categories/[id]`
+
+Delete a category record. This will remove the category from all associated posts.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | text | Yes | Category name |
+| slug | text | Yes | URL-friendly slug (auto-generated if not provided) |
+| description | textarea | No | Category description |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Post-Category Relationship
+
+Categories are linked to posts through a `post_categories` pivot table. When filtering posts by category:
+
+1. Use the [Public Posts API](/api/v1/theme/blog/posts/public) with `category` query parameter
+2. Query the pivot table directly for advanced filtering
+
+## Features
+
+- **Searchable**: name, description
+- **Sortable**: All fields
+- **Metadata**: Supported
+
+## Permissions
+
+- **Create/Update/Delete**: Owner only
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Category doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Posts](/api/v1/posts)** - Blog posts
+- **[Public Posts](/api/v1/theme/blog/posts/public)** - Filter by category