@bloomneo/appkit 1.2.9

package/bin/templates/feature/feature.service.ts.template

@@ -0,0 +1,81 @@
+/**
+ * {{featureName}} Feature Service - Business logic with AppKit integration
+ * @module {{projectName}}/{{featureName}}-service
+ * @file src/api/features/{{featureName}}/{{featureName}}.service.ts
+ *
+ * @llm-rule WHEN: Need business logic layer with validation, logging, and config
+ * @llm-rule AVOID: Direct database calls from routes - always use service layer
+ * @llm-rule NOTE: Demonstrates AppKit logger, config, and error patterns for FBCA
+ */
+
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { configClass } from '@bloomneo/appkit/config';
+import { errorClass } from '@bloomneo/appkit/error';
+import type { {{featureName}}Response, {{featureName}}CreateRequest } from './{{featureName}}.types.js';
+
+// Initialize AppKit modules following the pattern
+const logger = loggerClass.get('{{featureName}}');
+const config = configClass.get();
+const error = errorClass.get();
+
+export const {{featureName}}Service = {
+  /**
+   * Get all {{featureName}} items
+   */
+  async getAll(): Promise<{{featureName}}Response[]> {
+    try {
+      logger.info('Processing get all {{featureName}} request');
+
+      // Example implementation - replace with your business logic
+      const items = [
+        {
+          id: '1',
+          name: 'Sample {{featureName}}',
+          timestamp: new Date().toISOString()
+        }
+      ];
+
+      logger.info('Get all {{featureName}} request completed', { count: items.length });
+      return items;
+
+    } catch (err) {
+      logger.error('Failed to get all {{featureName}} items', { error: err });
+      throw error.serverError('Failed to retrieve {{featureName}} items');
+    }
+  },
+
+  /**
+   * Get {{featureName}} by ID
+   */
+  async getById(id: string): Promise<{{featureName}}Response> {
+    try {
+      logger.info('Processing get {{featureName}} by ID request', { id });
+
+      // Validate input
+      if (!id || typeof id !== 'string') {
+        logger.warn('Invalid ID provided', { id });
+        throw error.badRequest('ID must be a valid string');
+      }
+
+      // Example implementation - replace with your business logic
+      const item = {
+        id,
+        name: `Sample {{featureName}} ${id}`,
+        timestamp: new Date().toISOString()
+      };
+
+      logger.info('Get {{featureName}} by ID request completed', { id, result: item });
+      return item;
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to get {{featureName}} by ID', { id, error: err });
+      throw error.serverError('Failed to retrieve {{featureName}} item');
+    }
+  }
+};

package/bin/templates/feature/feature.types.ts.template

@@ -0,0 +1,23 @@
+/**
+ * {{featureName}} Feature Type Definitions - Shared interfaces and types
+ * @module {{projectName}}/{{featureName}}-types
+ * @file src/api/features/{{featureName}}/{{featureName}}.types.ts
+ *
+ * @llm-rule WHEN: Need type safety for {{featureName}} feature data structures
+ * @llm-rule AVOID: Defining types inline - reduces reusability and consistency
+ * @llm-rule NOTE: Shared across service and route layers for type consistency
+ */
+
+export interface {{featureName}}Response {
+  id: string;
+  name: string;
+  timestamp: string;
+}
+
+export interface {{featureName}}CreateRequest {
+  name: string;
+}
+
+export interface {{featureName}}UpdateRequest {
+  name?: string;
+}

package/bin/templates/feature-db/feature.http.template

@@ -0,0 +1,63 @@
+### {{FeatureName}} API Testing with Frontend Key
+### Base URL: http://localhost:3000
+### Note: In development, X-Frontend-Key is not required but shown for testing
+
+### 1. Get all {{featureName}} (without key - should work in dev)
+GET http://localhost:3000/api/{{featureName}}
+
+###
+
+### 2. Get all {{featureName}} (with frontend key)
+GET http://localhost:3000/api/{{featureName}}
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 3. Create a new {{featureName}} (with frontend key)
+POST http://localhost:3000/api/{{featureName}}
+Content-Type: application/json
+X-Frontend-Key: {{frontendKey}}
+
+{
+  "name": "Sample {{FeatureName}}"
+}
+
+###
+
+### 4. Get {{featureName}} by ID (with frontend key)
+GET http://localhost:3000/api/{{featureName}}/1
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 5. Update {{featureName}} by ID (with frontend key)
+PUT http://localhost:3000/api/{{featureName}}/1
+Content-Type: application/json
+X-Frontend-Key: {{frontendKey}}
+
+{
+  "name": "Updated {{FeatureName}}"
+}
+
+###
+
+### 6. Delete {{featureName}} by ID (with frontend key)
+DELETE http://localhost:3000/api/{{featureName}}/1
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 7. Test with wrong key (should fail in production)
+GET http://localhost:3000/api/{{featureName}}
+X-Frontend-Key: wrong_key_123
+
+###
+
+### Health Check (not protected)
+GET http://localhost:3000/health
+
+###
+
+### API Info (protected)
+GET http://localhost:3000/api
+X-Frontend-Key: {{frontendKey}}

package/bin/templates/feature-db/feature.model.ts.template

@@ -0,0 +1,74 @@
+/**
+ * {{FeatureName}} Model - Database operations with Prisma
+ * @module {{projectName}}/{{featureName}}-model
+ * @file src/api/features/{{featureName}}/{{featureName}}.model.ts
+ *
+ * @llm-rule WHEN: Need database layer separation for {{featureName}} feature
+ * @llm-rule AVOID: Database operations directly in service - use model layer
+ * @llm-rule NOTE: Handles all Prisma database operations for {{featureName}} feature
+ */
+
+import { databaseClass } from '@bloomneo/appkit/database';
+import { loggerClass } from '@bloomneo/appkit/logger';
+
+const logger = loggerClass.get('{{featureName}}-model');
+
+export const model = {
+  /**
+   * Get all {{featureName}} from database
+   */
+  async findAll() {
+    logger.info('Finding all {{featureName}}');
+    const db = await databaseClass.get();
+    return await db.{{tableName}}.findMany({
+      orderBy: { createdAt: 'desc' }
+    });
+  },
+
+  /**
+   * Find {{featureName}} by ID
+   */
+  async findById(id: number) {
+    logger.info('Finding {{featureName}} by ID', { id });
+    const db = await databaseClass.get();
+    return await db.{{tableName}}.findUnique({
+      where: { id }
+    });
+  },
+
+  /**
+   * Create new {{featureName}}
+   */
+  async create(data: { name: string }) {
+    logger.info('Creating new {{featureName}}', { data });
+    const db = await databaseClass.get();
+    return await db.{{tableName}}.create({
+      data: {
+        name: data.name.trim(),
+      }
+    });
+  },
+
+  /**
+   * Update {{featureName}} by ID
+   */
+  async update(id: number, data: { name?: string }) {
+    logger.info('Updating {{featureName}}', { id, data });
+    const db = await databaseClass.get();
+    return await db.{{tableName}}.update({
+      where: { id },
+      data
+    });
+  },
+
+  /**
+   * Delete {{featureName}} by ID
+   */
+  async delete(id: number) {
+    logger.info('Deleting {{featureName}}', { id });
+    const db = await databaseClass.get();
+    return await db.{{tableName}}.delete({
+      where: { id }
+    });
+  }
+};

package/bin/templates/feature-db/feature.route.ts.template

@@ -0,0 +1,58 @@
+/**
+ * {{FeatureName}} Feature Routes - Express endpoints with AppKit integration
+ * @module {{projectName}}/{{featureName}}-routes
+ * @file src/api/features/{{featureName}}/{{featureName}}.route.ts
+ *
+ * @llm-rule WHEN: Need HTTP endpoints for {{featureName}} feature with error handling and database operations
+ * @llm-rule AVOID: Adding routes without asyncRoute wrapper - breaks error handling
+ * @llm-rule NOTE: Auto-discovered by router.ts, exports default Express router, supports full CRUD operations
+ */
+
+import express from 'express';
+import { errorClass } from '@bloomneo/appkit/error';
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { {{featureName}}Service } from './{{featureName}}.service.js';
+
+const router = express.Router();
+const error = errorClass.get();
+const logger = loggerClass.get('{{featureName}}-routes');
+
+// GET /api/{{featureName}} - Get all {{featureName}} items
+router.get('/', error.asyncRoute(async (_req, res) => {
+  logger.info('GET /api/{{featureName}} request received');
+  const result = await {{featureName}}Service.getAll();
+  res.json(result);
+}));
+
+// POST /api/{{featureName}} - Create new {{featureName}}
+router.post('/', error.asyncRoute(async (req, res) => {
+  logger.info('POST /api/{{featureName}} request received', { body: req.body });
+  const result = await {{featureName}}Service.create(req.body);
+  res.status(201).json(result);
+}));
+
+// GET /api/{{featureName}}/:id - Get specific {{featureName}} by ID
+router.get('/:id', error.asyncRoute(async (req, res) => {
+  const id = req.params.id;
+  logger.info('GET /api/{{featureName}}/:id request received', { id });
+  const result = await {{featureName}}Service.getById(id);
+  res.json(result);
+}));
+
+// PUT /api/{{featureName}}/:id - Update {{featureName}} by ID
+router.put('/:id', error.asyncRoute(async (req, res) => {
+  const id = req.params.id;
+  logger.info('PUT /api/{{featureName}}/:id request received', { id, body: req.body });
+  const result = await {{featureName}}Service.update(id, req.body);
+  res.json(result);
+}));
+
+// DELETE /api/{{featureName}}/:id - Delete {{featureName}} by ID
+router.delete('/:id', error.asyncRoute(async (req, res) => {
+  const id = req.params.id;
+  logger.info('DELETE /api/{{featureName}}/:id request received', { id });
+  await {{featureName}}Service.delete(id);
+  res.status(200).json({ message: 'Deleted successfully' });
+}));
+
+export default router;

package/bin/templates/feature-db/feature.service.ts.template

@@ -0,0 +1,231 @@
+/**
+ * {{FeatureName}} Feature Service - Business logic with AppKit database integration
+ * @module {{projectName}}/{{featureName}}-service
+ * @file src/api/features/{{featureName}}/{{featureName}}.service.ts
+ *
+ * @llm-rule WHEN: Need business logic layer with validation, logging, config, and database access
+ * @llm-rule AVOID: Direct database calls from routes - always use service layer
+ * @llm-rule NOTE: Demonstrates AppKit database, logger, config, and error patterns for FBCA with Prisma
+ */
+
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { errorClass } from '@bloomneo/appkit/error';
+import { model } from './{{featureName}}.model.js';
+import type { {{FeatureName}}Response, {{FeatureName}}CreateRequest, {{FeatureName}}UpdateRequest } from './{{featureName}}.types.js';
+
+// Initialize AppKit modules following the pattern
+const logger = loggerClass.get('{{featureName}}');
+const error = errorClass.get();
+
+export const {{featureName}}Service = {
+  /**
+   * Get all {{featureName}} items
+   */
+  async getAll(): Promise<{{FeatureName}}Response[]> {
+    try {
+      logger.info('Processing get all {{featureName}} request');
+
+      const items = await model.findAll();
+
+      // Transform to response format
+      const result = items.map((item: any) => ({
+        ...item,
+        createdAt: item.createdAt.toISOString(),
+        updatedAt: item.updatedAt.toISOString()
+      }));
+
+      logger.info('Get all {{featureName}} request completed', { count: result.length });
+      return result;
+
+    } catch (err) {
+      logger.error('Failed to get all {{featureName}} items', { error: err });
+      throw error.serverError('Failed to retrieve {{featureName}} items');
+    }
+  },
+
+  /**
+   * Get {{featureName}} by ID
+   */
+  async getById(id: string): Promise<{{FeatureName}}Response> {
+    try {
+      logger.info('Processing get {{featureName}} by ID request', { id });
+
+      // Validate and convert ID to number
+      const numId = parseInt(id, 10);
+      if (!id || isNaN(numId)) {
+        logger.warn('Invalid ID provided', { id });
+        throw error.badRequest('ID must be a valid number');
+      }
+
+      const item = await model.findById(numId);
+
+      if (!item) {
+        logger.warn('{{FeatureName}} not found', { id });
+        throw error.notFound('{{FeatureName}} not found');
+      }
+
+      // Transform to response format
+      const result = {
+        ...item,
+        createdAt: item.createdAt.toISOString(),
+        updatedAt: item.updatedAt.toISOString()
+      };
+
+      logger.info('Get {{featureName}} by ID request completed', { id, result });
+      return result;
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to get {{featureName}} by ID', { id, error: err });
+      throw error.serverError('Failed to retrieve {{featureName}} item');
+    }
+  },
+
+  /**
+   * Create a new {{featureName}}
+   */
+  async create(data: {{FeatureName}}CreateRequest): Promise<{{FeatureName}}Response> {
+    try {
+      logger.info('Processing create {{featureName}} request', { data });
+
+      // Validate input
+      if (!data.name || typeof data.name !== 'string' || data.name.trim().length === 0) {
+        logger.warn('Invalid name provided', { data });
+        throw error.badRequest('Name is required and must be a non-empty string');
+      }
+
+      if (data.name.length > 200) {
+        logger.warn('Name too long', { nameLength: data.name.length });
+        throw error.badRequest('Name must be less than 200 characters');
+      }
+
+      const item = await model.create({
+        name: data.name.trim()
+      });
+
+      // Transform to response format
+      const result = {
+        ...item,
+        createdAt: item.createdAt.toISOString(),
+        updatedAt: item.updatedAt.toISOString()
+      };
+
+      logger.info('Create {{featureName}} request completed', { id: item.id, result });
+      return result;
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to create {{featureName}}', { data, error: err });
+      throw error.serverError('Failed to create {{featureName}} item');
+    }
+  },
+
+  /**
+   * Update a {{featureName}}
+   */
+  async update(id: string, data: {{FeatureName}}UpdateRequest): Promise<{{FeatureName}}Response> {
+    try {
+      logger.info('Processing update {{featureName}} request', { id, data });
+
+      // Validate and convert ID to number
+      const numId = parseInt(id, 10);
+      if (!id || isNaN(numId)) {
+        logger.warn('Invalid ID provided', { id });
+        throw error.badRequest('ID must be a valid number');
+      }
+
+      if (data.name !== undefined) {
+        if (typeof data.name !== 'string' || data.name.trim().length === 0) {
+          logger.warn('Invalid name provided', { data });
+          throw error.badRequest('Name must be a non-empty string');
+        }
+        if (data.name.length > 200) {
+          logger.warn('Name too long', { nameLength: data.name.length });
+          throw error.badRequest('Name must be less than 200 characters');
+        }
+      }
+
+      // Check if item exists
+      const existingItem = await model.findById(numId);
+
+      if (!existingItem) {
+        logger.warn('{{FeatureName}} not found for update', { id });
+        throw error.notFound('{{FeatureName}} not found');
+      }
+
+      // Build update data
+      const updateData: any = {};
+      if (data.name !== undefined) updateData.name = data.name.trim();
+
+      const item = await model.update(numId, updateData);
+
+      // Transform to response format
+      const result = {
+        ...item,
+        createdAt: item.createdAt.toISOString(),
+        updatedAt: item.updatedAt.toISOString()
+      };
+
+      logger.info('Update {{featureName}} request completed', { id, result });
+      return result;
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to update {{featureName}}', { id, data, error: err });
+      throw error.serverError('Failed to update {{featureName}} item');
+    }
+  },
+
+  /**
+   * Delete a {{featureName}}
+   */
+  async delete(id: string): Promise<void> {
+    try {
+      logger.info('Processing delete {{featureName}} request', { id });
+
+      // Validate and convert ID to number
+      const numId = parseInt(id, 10);
+      if (!id || isNaN(numId)) {
+        logger.warn('Invalid ID provided', { id });
+        throw error.badRequest('ID must be a valid number');
+      }
+
+      // Check if item exists
+      const existingItem = await model.findById(numId);
+
+      if (!existingItem) {
+        logger.warn('{{FeatureName}} not found for deletion', { id });
+        throw error.notFound('{{FeatureName}} not found');
+      }
+
+      await model.delete(numId);
+
+      logger.info('Delete {{featureName}} request completed', { id });
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to delete {{featureName}}', { id, error: err });
+      throw error.serverError('Failed to delete {{featureName}} item');
+    }
+  }
+};

package/bin/templates/feature-db/feature.types.ts.template

@@ -0,0 +1,25 @@
+/**
+ * {{FeatureName}} Feature Type Definitions - Shared interfaces and types
+ * @module {{projectName}}/{{featureName}}-types
+ * @file src/api/features/{{featureName}}/{{featureName}}.types.ts
+ *
+ * @llm-rule WHEN: Need type safety for {{featureName}} feature data structures with database support
+ * @llm-rule AVOID: Defining types inline - reduces reusability and consistency
+ * @llm-rule NOTE: Shared across service and route layers for type consistency, includes Prisma model types
+ */
+
+export interface {{FeatureName}}Response {
+  id: number;
+  name: string;
+  tenant_id: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface {{FeatureName}}CreateRequest {
+  name: string;
+}
+
+export interface {{FeatureName}}UpdateRequest {
+  name?: string;
+}

package/bin/templates/feature-db/schema-addition.prisma.template

@@ -0,0 +1,9 @@
+model {{FeatureName}} {
+  id          Int       @id @default(autoincrement())
+  name        String
+  tenant_id   String?   // Mandatory for AppKit multi-tenant support
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@map("{{tableName}}")
+}

package/bin/templates/feature-db/seeding/README.md.template

@@ -0,0 +1,57 @@
+# Database Seeding
+
+This folder contains individual seed files for each feature. Each seed file is independent and can be run separately.
+
+## Running Individual Seeds
+
+```bash
+# Seed {{featureName}} data only
+node prisma/seeding/{{featureName}}.seed.js
+```
+
+## Running All Seeds
+
+Create a main seed file in your project root to run all feature seeds:
+
+```javascript
+// prisma/seed.js
+import { seed{{FeatureName}} } from './seeding/{{featureName}}.seed.js';
+
+async function main() {
+  console.log('🌱 Starting database seeding...');
+
+  await seed{{FeatureName}}();
+  // Add other feature seeds here as you create them
+
+  console.log('✅ Database seeding completed!');
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });
+```
+
+## Adding to package.json
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "seed": "node prisma/seed.js",
+    "seed:{{featureName}}": "node prisma/seeding/{{featureName}}.seed.js"
+  }
+}
+```
+
+## Features
+
+- ✅ **Non-destructive**: Won't overwrite existing data
+- ✅ **Independent**: Each feature can be seeded separately
+- ✅ **Safe**: Checks for existing data before seeding
+- ✅ **Informative**: Clear console output about what's happening

package/bin/templates/feature-db/seeding/feature.seed.js.template

@@ -0,0 +1,67 @@
+/**
+ * {{FeatureName}} Feature Seed Data
+ * @file prisma/seeding/{{featureName}}.seed.js
+ *
+ * Run this seed file individually:
+ * node prisma/seeding/{{featureName}}.seed.js
+ *
+ * Or include in your main seed file:
+ * require('./seeding/{{featureName}}.seed.js');
+ */
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+export async function seed{{FeatureName}}() {
+  console.log('🌱 Seeding {{featureName}} data...');
+
+  try {
+    // Check if {{featureName}} data already exists
+    const existingCount = await prisma.{{tableName}}.count();
+
+    if (existingCount > 0) {
+      console.log(`⚠️  {{FeatureName}} table already has ${existingCount} records. Skipping seed...`);
+      return { skipped: true, count: existingCount };
+    }
+
+    // Create sample {{featureName}} data
+    const {{featureName}}Data = [
+      {
+        name: 'Sample {{FeatureName}} 1',
+      },
+      {
+        name: 'Sample {{FeatureName}} 2',
+      },
+      {
+        name: 'Sample {{FeatureName}} 3',
+      },
+    ];
+
+    const result = await prisma.{{tableName}}.createMany({
+      data: {{featureName}}Data
+    });
+
+    console.log(`✅ Successfully seeded ${result.count} {{featureName}} records`);
+    return { seeded: true, count: result.count };
+
+  } catch (error) {
+    console.error(`❌ Error seeding {{featureName}} data:`, error);
+    throw error;
+  }
+}
+
+// Run directly if this file is executed
+if (import.meta.url === `file://${process.argv[1]}`) {
+  seed{{FeatureName}}()
+    .then((result) => {
+      console.log('{{FeatureName}} seeding completed:', result);
+    })
+    .catch((error) => {
+      console.error('{{FeatureName}} seeding failed:', error);
+      process.exit(1);
+    })
+    .finally(async () => {
+      await prisma.$disconnect();
+    });
+}