@egdesk/next-api-plugin 1.0.0

package/src/generate-helpers.ts

@@ -0,0 +1,140 @@
+/**
+ * Generate helper functions for EGDesk database access in Next.js
+ *
+ * Creates egdesk-helpers.ts with type-safe helper functions.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Generate egdesk-helpers.ts file
+ */
+export function generateHelpers(projectPath: string): void {
+  const helperPath = path.join(projectPath, 'egdesk-helpers.ts');
+
+  const helperContent = `/**
+ * EGDesk User Data Helper Functions for Next.js
+ *
+ * Type-safe helpers for accessing EGDesk user data.
+ * Works in both client and server components.
+ *
+ * Generated by @egdesk/next-api-plugin
+ */
+
+/**
+ * Call EGDesk user-data MCP tool
+ *
+ * Uses a proxy endpoint to work in both local and tunneled environments.
+ * The Next.js middleware intercepts these requests and forwards them to localhost:8080.
+ */
+export async function callUserDataTool(
+  toolName: string,
+  args: Record<string, any> = {}
+): Promise<any> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json'
+  };
+
+  // Use proxy endpoint - works in both local and tunneled environments
+  // Absolute URL with leading slash to ensure correct resolution from any route
+  const response = await fetch('/__user_data_proxy', {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ tool: toolName, arguments: args })
+  });
+
+  if (!response.ok) {
+    throw new Error(\`HTTP \${response.status}: \${response.statusText}\`);
+  }
+
+  const result = await response.json();
+
+  if (!result.success) {
+    throw new Error(result.error || 'Tool call failed');
+  }
+
+  // Parse MCP response format
+  const content = result.result?.content?.[0]?.text;
+  return content ? JSON.parse(content) : null;
+}
+
+/**
+ * Query table data
+ */
+export async function queryTable(
+  tableName: string,
+  options: {
+    filters?: Record<string, string>;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'ASC' | 'DESC';
+  } = {}
+) {
+  return callUserDataTool('user_data_query', {
+    tableName,
+    ...options
+  });
+}
+
+/**
+ * Search table
+ */
+export async function searchTable(
+  tableName: string,
+  searchQuery: string,
+  limit: number = 50
+) {
+  return callUserDataTool('user_data_search', {
+    tableName,
+    searchQuery,
+    limit
+  });
+}
+
+/**
+ * Aggregate data
+ */
+export async function aggregateTable(
+  tableName: string,
+  column: string,
+  aggregateFunction: 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT',
+  options: {
+    filters?: Record<string, string>;
+    groupBy?: string;
+  } = {}
+) {
+  return callUserDataTool('user_data_aggregate', {
+    tableName,
+    column,
+    function: aggregateFunction,
+    ...options
+  });
+}
+
+/**
+ * Execute raw SQL query
+ */
+export async function executeSQL(query: string) {
+  return callUserDataTool('user_data_sql_query', { query });
+}
+
+/**
+ * List all available tables
+ */
+export async function listTables() {
+  return callUserDataTool('user_data_list_tables', {});
+}
+
+/**
+ * Get table schema
+ */
+export async function getTableSchema(tableName: string) {
+  return callUserDataTool('user_data_get_schema', { tableName });
+}
+`;
+
+  fs.writeFileSync(helperPath, helperContent, 'utf-8');
+  console.log(`✅ Generated ${helperPath}`);
+}

package/src/generate-middleware.ts

@@ -0,0 +1,108 @@
+/**
+ * Generate Next.js middleware for EGDesk database proxy
+ *
+ * Creates middleware.ts that intercepts __user_data_proxy requests
+ * and forwards them to the EGDesk MCP server.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Detect if project uses src/ directory structure
+ */
+function usesSrcDirectory(projectPath: string): boolean {
+  const srcPath = path.join(projectPath, 'src');
+  const srcAppPath = path.join(projectPath, 'src', 'app');
+  return fs.existsSync(srcPath) && fs.existsSync(srcAppPath);
+}
+
+/**
+ * Generate middleware.ts file in the correct location (root or src/)
+ */
+export function generateMiddleware(projectPath: string): void {
+  // Detect if project uses src/ directory
+  const hasSrc = usesSrcDirectory(projectPath);
+  const targetDir = hasSrc ? path.join(projectPath, 'src') : projectPath;
+  const middlewarePath = path.join(targetDir, 'middleware.ts');
+
+  console.log(`📁 Detected ${hasSrc ? 'src/' : 'root'} directory structure`);
+  console.log(`📝 Generating middleware at: ${middlewarePath}`);
+
+  // Check if middleware.ts already exists
+  if (fs.existsSync(middlewarePath)) {
+    console.log('⚠️  middleware.ts already exists - backing up to middleware.backup.ts');
+    const backupPath = path.join(targetDir, 'middleware.backup.ts');
+    fs.copyFileSync(middlewarePath, backupPath);
+  }
+
+  const middlewareContent = `import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+/**
+ * EGDesk Database Proxy Middleware
+ *
+ * Intercepts __user_data_proxy requests and forwards them to the EGDesk MCP server.
+ * This allows CORS-free database access in both local and tunneled environments.
+ *
+ * Generated by @egdesk/next-api-plugin
+ */
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Intercept __user_data_proxy requests
+  if (pathname.includes('__user_data_proxy')) {
+    try {
+      const body = await request.text();
+
+      // Read API key and URL from environment
+      const apiKey = process.env.NEXT_PUBLIC_EGDESK_API_KEY;
+      const apiUrl = process.env.NEXT_PUBLIC_EGDESK_API_URL || 'http://localhost:8080';
+
+      const headers: HeadersInit = {
+        'Content-Type': 'application/json',
+      };
+
+      if (apiKey) {
+        headers['X-Api-Key'] = apiKey;
+      }
+
+      // Forward to EGDesk MCP server
+      const response = await fetch(\`\${apiUrl}/user-data/tools/call\`, {
+        method: 'POST',
+        headers,
+        body,
+      });
+
+      const result = await response.json();
+
+      return NextResponse.json(result, { status: response.status });
+    } catch (error: any) {
+      return NextResponse.json(
+        { error: 'Proxy error', message: error.message },
+        { status: 500 }
+      );
+    }
+  }
+
+  // Continue to next middleware or route
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - api (API routes)
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     */
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
+};
+`;
+
+  fs.writeFileSync(middlewarePath, middlewareContent, 'utf-8');
+  console.log(`✅ Generated ${middlewarePath}`);
+}

package/src/generate-proxy.ts

@@ -0,0 +1,107 @@
+/**
+ * Generate Next.js 16+ proxy for EGDesk database proxy
+ *
+ * Creates proxy.ts that intercepts __user_data_proxy requests
+ * and forwards them to the EGDesk MCP server.
+ *
+ * This is the Next.js 16+ recommended approach (replaces middleware.ts)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Detect if project uses src/ directory structure
+ */
+function usesSrcDirectory(projectPath: string): boolean {
+  const srcPath = path.join(projectPath, 'src');
+  const srcAppPath = path.join(projectPath, 'src', 'app');
+  return fs.existsSync(srcPath) && fs.existsSync(srcAppPath);
+}
+
+/**
+ * Generate proxy.ts file in the correct location (root or src/)
+ */
+export function generateProxy(projectPath: string): void {
+  // Detect if project uses src/ directory
+  const hasSrc = usesSrcDirectory(projectPath);
+  const targetDir = hasSrc ? path.join(projectPath, 'src') : projectPath;
+  const proxyPath = path.join(targetDir, 'proxy.ts');
+
+  console.log(`📁 Detected ${hasSrc ? 'src/' : 'root'} directory structure`);
+  console.log(`📝 Generating proxy at: ${proxyPath}`);
+
+  // Check if proxy.ts already exists
+  if (fs.existsSync(proxyPath)) {
+    console.log('⚠️  proxy.ts already exists - backing up to proxy.backup.ts');
+    const backupPath = path.join(targetDir, 'proxy.backup.ts');
+    fs.copyFileSync(proxyPath, backupPath);
+  }
+
+  const proxyContent = `import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+/**
+ * EGDesk Database Proxy (Next.js 16+)
+ *
+ * Intercepts __user_data_proxy requests and forwards them to the EGDesk MCP server.
+ * This allows CORS-free database access in both local and tunneled environments.
+ *
+ * Generated by @egdesk/next-api-plugin
+ */
+export async function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Intercept __user_data_proxy requests
+  if (pathname.includes('__user_data_proxy')) {
+    try {
+      const body = await request.text();
+
+      // Read API key and URL from environment
+      const apiKey = process.env.NEXT_PUBLIC_EGDESK_API_KEY;
+      const apiUrl = process.env.NEXT_PUBLIC_EGDESK_API_URL || 'http://localhost:8080';
+
+      const headers: HeadersInit = {
+        'Content-Type': 'application/json',
+      };
+
+      if (apiKey) {
+        headers['X-Api-Key'] = apiKey;
+      }
+
+      // Forward to EGDesk MCP server
+      const response = await fetch(\`\${apiUrl}/user-data/tools/call\`, {
+        method: 'POST',
+        headers,
+        body,
+      });
+
+      const result = await response.json();
+
+      return NextResponse.json(result, { status: response.status });
+    } catch (error: any) {
+      return NextResponse.json(
+        { error: 'Proxy error', message: error.message },
+        { status: 500 }
+      );
+    }
+  }
+
+  // Continue to next proxy or route
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    /*
+     * Match all paths except static assets
+     * The proxy function itself filters for __user_data_proxy
+     */
+    '/:path*',
+  ],
+};
+`;
+
+  fs.writeFileSync(proxyPath, proxyContent, 'utf-8');
+  console.log(`✅ Generated ${proxyPath}`);
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * @egdesk/next-api-plugin
+ *
+ * Next.js plugin for EGDesk database proxy integration.
+ * Provides middleware-based database access for Next.js applications.
+ */
+
+import {
+  discoverTables,
+  updateEnvLocal,
+  generateConfigFile,
+  type UserDataConfig,
+  type UserDataTable
+} from './setup-userdata';
+import { generateMiddleware } from './generate-middleware';
+import { generateProxy } from './generate-proxy';
+import { generateHelpers } from './generate-helpers';
+
+export interface SetupOptions {
+  egdeskUrl?: string;
+  apiKey?: string;
+  useProxy?: boolean; // Use proxy.ts (Next.js 16+) instead of middleware.ts
+}
+
+/**
+ * Main setup function for Next.js projects
+ *
+ * Discovers tables and generates all necessary files:
+ * - proxy.ts or middleware.ts (proxy interceptor)
+ * - egdesk.config.ts (table definitions)
+ * - egdesk-helpers.ts (helper functions)
+ * - .env.local (environment variables)
+ */
+export async function setupNextApiPlugin(
+  projectPath: string,
+  options: SetupOptions = {}
+): Promise<void> {
+  const { egdeskUrl = 'http://localhost:8080', apiKey, useProxy = true } = options;
+
+  console.log('🔍 Discovering EGDesk user-data tables...');
+
+  try {
+    const tables = await discoverTables(egdeskUrl, apiKey);
+
+    if (tables.length === 0) {
+      console.warn('⚠️  No tables found. Import data in EGDesk first.');
+      console.log('');
+      console.log('Generating files anyway with empty table list...');
+    } else {
+      console.log(`✅ Found ${tables.length} table(s):`);
+      tables.forEach((table, index) => {
+        console.log(`   ${index + 1}. ${table.displayName} (${table.rowCount} rows)`);
+      });
+    }
+
+    const config: UserDataConfig = {
+      apiKey: apiKey || null,
+      baseUrl: egdeskUrl,
+      tables,
+      generatedAt: new Date().toISOString()
+    };
+
+    // Generate all configuration files
+    console.log('');
+    console.log('📝 Generating configuration files...');
+
+    // Use proxy.ts (Next.js 16+) or middleware.ts (legacy)
+    if (useProxy) {
+      console.log('🔄 Using proxy.ts (Next.js 16+ recommended)');
+      generateProxy(projectPath);
+    } else {
+      console.log('🔄 Using middleware.ts (legacy)');
+      generateMiddleware(projectPath);
+    }
+
+    generateConfigFile(projectPath, config);
+    generateHelpers(projectPath);
+    updateEnvLocal(projectPath, config);
+
+    const proxyFile = useProxy ? 'proxy.ts' : 'middleware.ts';
+
+    console.log('');
+    console.log('✅ Setup complete! Files generated:');
+    console.log(`   - ${proxyFile} (database proxy)`);
+    console.log('   - egdesk.config.ts (type-safe config)');
+    console.log('   - egdesk-helpers.ts (helper functions)');
+    console.log('   - .env.local (environment variables)');
+    console.log('');
+    console.log('📝 Next steps:');
+    console.log('   1. Add .env.local to your .gitignore');
+    console.log('   2. Restart your Next.js dev server');
+    console.log('   3. Import and use helpers in your components:');
+    console.log('      import { queryTable } from "./egdesk-helpers"');
+    console.log('      import { TABLES } from "./egdesk.config"');
+    console.log('');
+    console.log('Example usage in a component:');
+    console.log('   const data = await queryTable(TABLES.table1.name, { limit: 10 });');
+  } catch (error) {
+    console.error('❌ Setup failed:', error);
+    throw error;
+  }
+}
+
+// Export types and utilities
+export type { UserDataTable, UserDataConfig } from './setup-userdata';
+export { discoverTables } from './setup-userdata';
+export { generateMiddleware } from './generate-middleware';
+export { generateProxy } from './generate-proxy';
+export { generateHelpers } from './generate-helpers';

package/src/setup-userdata.ts

@@ -0,0 +1,238 @@
+/**
+ * User Data Setup Utility for Next.js
+ *
+ * Automatically discovers EGDesk user-data tables and generates configuration
+ * for Next.js projects to access them.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface UserDataTable {
+  id: string;
+  tableName: string;
+  displayName: string;
+  description?: string;
+  rowCount: number;
+  columnCount: number;
+  columns: string[];
+}
+
+export interface UserDataConfig {
+  apiKey: string | null;
+  baseUrl: string;
+  tables: UserDataTable[];
+  generatedAt: string;
+}
+
+/**
+ * Fetch available tables from EGDesk
+ */
+export async function discoverTables(
+  egdeskUrl: string = 'http://localhost:8080',
+  apiKey?: string
+): Promise<UserDataTable[]> {
+  try {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json'
+    };
+
+    if (apiKey) {
+      headers['X-Api-Key'] = apiKey;
+    }
+
+    // List all tables
+    const listResponse = await fetch(`${egdeskUrl}/user-data/tools/call`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        tool: 'user_data_list_tables',
+        arguments: {}
+      })
+    });
+
+    if (!listResponse.ok) {
+      throw new Error(`Failed to list tables: ${listResponse.statusText}`);
+    }
+
+    const listResult = await listResponse.json();
+
+    if (!listResult.success) {
+      throw new Error(listResult.error || 'Failed to list tables');
+    }
+
+    // Parse MCP response
+    const content = listResult.result?.content?.[0]?.text;
+    const data = content ? JSON.parse(content) : null;
+
+    if (!data || !data.tables) {
+      return [];
+    }
+
+    // Fetch schema for each table to get column names
+    const tablesWithColumns: UserDataTable[] = [];
+
+    for (const table of data.tables) {
+      try {
+        const schemaResponse = await fetch(`${egdeskUrl}/user-data/tools/call`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({
+            tool: 'user_data_get_schema',
+            arguments: { tableName: table.tableName }
+          })
+        });
+
+        if (schemaResponse.ok) {
+          const schemaResult = await schemaResponse.json();
+          const schemaContent = schemaResult.result?.content?.[0]?.text;
+          const schemaData = schemaContent ? JSON.parse(schemaContent) : null;
+
+          tablesWithColumns.push({
+            id: table.id,
+            tableName: table.tableName,
+            displayName: table.displayName,
+            description: table.description,
+            rowCount: table.rowCount,
+            columnCount: table.columnCount,
+            columns: schemaData?.schema?.map((col: any) => col.name) || []
+          });
+        }
+      } catch (error) {
+        console.warn(`Failed to fetch schema for ${table.tableName}:`, error);
+        // Add table without column info
+        tablesWithColumns.push({
+          ...table,
+          columns: []
+        });
+      }
+    }
+
+    return tablesWithColumns;
+  } catch (error) {
+    console.error('Failed to discover tables:', error);
+    throw error;
+  }
+}
+
+/**
+ * Read existing .env.local file or return empty object
+ */
+export function readEnvLocal(projectPath: string): Record<string, string> {
+  const envPath = path.join(projectPath, '.env.local');
+
+  if (!fs.existsSync(envPath)) {
+    return {};
+  }
+
+  const envContent = fs.readFileSync(envPath, 'utf-8');
+  const envVars: Record<string, string> = {};
+
+  for (const line of envContent.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const [key, ...valueParts] = trimmed.split('=');
+      if (key && valueParts.length > 0) {
+        envVars[key.trim()] = valueParts.join('=').trim();
+      }
+    }
+  }
+
+  return envVars;
+}
+
+/**
+ * Update .env.local file with Next.js environment variables
+ */
+export function updateEnvLocal(
+  projectPath: string,
+  config: UserDataConfig
+): void {
+  const envPath = path.join(projectPath, '.env.local');
+  const existingVars = readEnvLocal(projectPath);
+
+  // Merge with existing vars, prioritizing new EGDesk values
+  const newVars = {
+    ...existingVars,
+    'NEXT_PUBLIC_EGDESK_API_URL': config.baseUrl,
+    ...(config.apiKey && { 'NEXT_PUBLIC_EGDESK_API_KEY': config.apiKey })
+  };
+
+  const envContent = [
+    '# EGDesk User Data Configuration',
+    `# Generated at: ${config.generatedAt}`,
+    '',
+    ...Object.entries(newVars).map(([key, value]) => `${key}=${value}`),
+    '',
+    '# Available Tables',
+    `# Total tables: ${config.tables.length}`,
+    ...config.tables.map((table, index) =>
+      `# ${index + 1}. ${table.displayName} (${table.tableName}) - ${table.rowCount} rows, ${table.columnCount} columns`
+    ),
+    ''
+  ].join('\n');
+
+  fs.writeFileSync(envPath, envContent, 'utf-8');
+  console.log(`✅ Updated ${envPath}`);
+}
+
+/**
+ * Generate TypeScript config file with table definitions
+ */
+export function generateConfigFile(
+  projectPath: string,
+  config: UserDataConfig
+): void {
+  const configPath = path.join(projectPath, 'egdesk.config.ts');
+
+  const configContent = `/**
+ * EGDesk User Data Configuration
+ * Generated at: ${config.generatedAt}
+ *
+ * This file contains type-safe definitions for your EGDesk tables.
+ */
+
+export const EGDESK_CONFIG = {
+  apiUrl: '${config.baseUrl}',
+  apiKey: ${config.apiKey ? `'${config.apiKey}'` : 'undefined'},
+} as const;
+
+export interface TableDefinition {
+  name: string;
+  displayName: string;
+  description?: string;
+  rowCount: number;
+  columnCount: number;
+  columns: string[];
+}
+
+export const TABLES = {
+${config.tables.map((table, index) => `  table${index + 1}: {
+    name: '${table.tableName}',
+    displayName: '${table.displayName}',
+    description: ${table.description ? `'${table.description}'` : 'undefined'},
+    rowCount: ${table.rowCount},
+    columnCount: ${table.columnCount},
+    columns: [${table.columns.map(col => `'${col}'`).join(', ')}]
+  } as TableDefinition`).join(',\n')}
+} as const;
+
+${config.tables.length > 0 ? `
+// Main table (first table by default)
+export const MAIN_TABLE = TABLES.table1;
+` : ''}
+
+// Helper to get table by name
+export function getTableByName(tableName: string): TableDefinition | undefined {
+  return Object.values(TABLES).find(t => t.name === tableName);
+}
+
+// Export table names for easy access
+export const TABLE_NAMES = {
+${config.tables.map((table, index) => `  table${index + 1}: '${table.tableName}'`).join(',\n')}
+} as const;
+`;
+
+  fs.writeFileSync(configPath, configContent, 'utf-8');
+  console.log(`✅ Generated ${configPath}`);
+}