@egdesk/next-api-plugin 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+# @egdesk/next-api-plugin
+
+Next.js plugin for EGDesk database proxy integration. Provides middleware-based CORS-free database access for Next.js applications.
+
+## Features
+
+- 🔒 CORS-free database access via Next.js middleware
+- 🌐 Works in both local and tunneled environments
+- 📝 Type-safe table definitions and helper functions
+- 🚀 Auto-discovery of database tables
+- 🔧 Zero configuration after setup
+
+## Installation
+
+```bash
+npm install @egdesk/next-api-plugin
+# or
+yarn add @egdesk/next-api-plugin
+# or
+pnpm add @egdesk/next-api-plugin
+```
+
+## Quick Start
+
+1. Run the setup command in your Next.js project:
+
+```bash
+npx egdesk-next-setup
+```
+
+This will generate:
+- `middleware.ts` - Database proxy middleware
+- `egdesk.config.ts` - Type-safe table definitions
+- `egdesk-helpers.ts` - Helper functions for database access
+- `.env.local` - Environment variables
+
+2. Add `.env.local` to your `.gitignore` (if not already there)
+
+3. Restart your Next.js dev server
+
+4. Use the helpers in your components:
+
+```typescript
+import { queryTable } from './egdesk-helpers';
+import { TABLES } from './egdesk.config';
+
+export default async function MyPage() {
+  const data = await queryTable(TABLES.table1.name, { limit: 10 });
+
+  return (
+    <div>
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+The plugin uses Next.js environment variables:
+
+```env
+NEXT_PUBLIC_EGDESK_API_URL=http://localhost:8080
+NEXT_PUBLIC_EGDESK_API_KEY=your-api-key-here
+```
+
+### Custom Setup
+
+You can programmatically run the setup:
+
+```typescript
+import { setupNextApiPlugin } from '@egdesk/next-api-plugin';
+
+await setupNextApiPlugin('/path/to/project', {
+  egdeskUrl: 'http://localhost:8080',
+  apiKey: 'optional-api-key'
+});
+```
+
+## How It Works
+
+The plugin creates a Next.js middleware that intercepts requests to `__user_data_proxy` and forwards them to your EGDesk MCP server. This allows your Next.js app to make database queries without CORS issues, even in tunneled environments.
+
+**Request Flow:**
+1. Your component calls `queryTable()` or other helpers
+2. Helper makes a fetch to `__user_data_proxy`
+3. Next.js middleware intercepts the request
+4. Middleware forwards to `localhost:8080/user-data/tools/call`
+5. Response is returned to your component
+
+## API Reference
+
+### Helper Functions
+
+```typescript
+// Query table data
+queryTable(tableName: string, options?: {
+  filters?: Record<string, string>;
+  limit?: number;
+  offset?: number;
+  orderBy?: string;
+  orderDirection?: 'ASC' | 'DESC';
+})
+
+// Search table
+searchTable(tableName: string, searchQuery: string, limit?: number)
+
+// Aggregate data
+aggregateTable(tableName: string, column: string, aggregateFunction: 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT', options?: {
+  filters?: Record<string, string>;
+  groupBy?: string;
+})
+
+// Execute raw SQL
+executeSQL(query: string)
+
+// List all tables
+listTables()
+
+// Get table schema
+getTableSchema(tableName: string)
+```
+
+### Configuration Types
+
+```typescript
+interface TableDefinition {
+  name: string;
+  displayName: string;
+  description?: string;
+  rowCount: number;
+  columnCount: number;
+  columns: string[];
+}
+
+const TABLES = {
+  table1: TableDefinition,
+  table2: TableDefinition,
+  // ...
+}
+
+const TABLE_NAMES = {
+  table1: 'actual_table_name',
+  table2: 'another_table_name',
+  // ...
+}
+```
+
+## Troubleshooting
+
+### Middleware not working
+
+Make sure:
+- `middleware.ts` is in your project root (not in `src/` or `app/`)
+- Your Next.js version is 13.0.0 or higher
+- You've restarted your dev server after setup
+
+### CORS errors
+
+If you're still seeing CORS errors:
+- Check that middleware.ts was generated correctly
+- Verify environment variables are set in `.env.local`
+- Make sure you're using the relative URL `__user_data_proxy` (no leading slash)
+
+### Table discovery fails
+
+Ensure:
+- EGDesk MCP server is running on `localhost:8080`
+- You have tables imported in EGDesk
+- API key is correct (if required)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for @egdesk/next-api-plugin
+ *
+ * Usage:
+ *   npx egdesk-next-setup
+ *   npx egdesk-next-setup --url http://localhost:8080 --api-key YOUR_KEY
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CLI entry point for @egdesk/next-api-plugin
+ *
+ * Usage:
+ *   npx egdesk-next-setup
+ *   npx egdesk-next-setup --url http://localhost:8080 --api-key YOUR_KEY
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse command line arguments
+    let egdeskUrl = 'http://localhost:8080';
+    let apiKey;
+    let useProxy = true; // Use proxy.ts by default (Next.js 16+)
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url' && i + 1 < args.length) {
+            egdeskUrl = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--api-key' && i + 1 < args.length) {
+            apiKey = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--legacy-middleware') {
+            useProxy = false;
+        }
+        else if (args[i] === '--help' || args[i] === '-h') {
+            console.log('Usage: egdesk-next-setup [options]');
+            console.log('');
+            console.log('Options:');
+            console.log('  --url <url>             EGDesk server URL (default: http://localhost:8080)');
+            console.log('  --api-key <key>         API key for authentication');
+            console.log('  --legacy-middleware     Use middleware.ts instead of proxy.ts (for Next.js <16)');
+            console.log('  --help, -h              Show this help message');
+            console.log('');
+            console.log('Example:');
+            console.log('  egdesk-next-setup --url http://localhost:8080 --api-key mykey');
+            console.log('  egdesk-next-setup --legacy-middleware  # For Next.js <16');
+            process.exit(0);
+        }
+    }
+    // Get current working directory (project root)
+    const projectPath = process.cwd();
+    console.log('🚀 EGDesk Next.js Setup');
+    console.log(`📂 Project: ${projectPath}`);
+    console.log(`🔗 EGDesk URL: ${egdeskUrl}`);
+    console.log('');
+    try {
+        await (0, index_1.setupNextApiPlugin)(projectPath, { egdeskUrl, apiKey, useProxy });
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Setup failed:', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/generate-helpers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate helper functions for EGDesk database access in Next.js
+ *
+ * Creates egdesk-helpers.ts with type-safe helper functions.
+ */
+/**
+ * Generate egdesk-helpers.ts file
+ */
+export declare function generateHelpers(projectPath: string): void;

package/dist/generate-helpers.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Generate helper functions for EGDesk database access in Next.js
+ *
+ * Creates egdesk-helpers.ts with type-safe helper functions.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateHelpers = generateHelpers;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Generate egdesk-helpers.ts file
+ */
+function generateHelpers(projectPath) {
+    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/dist/generate-middleware.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/**
+ * Generate middleware.ts file in the correct location (root or src/)
+ */
+export declare function generateMiddleware(projectPath: string): void;

package/dist/generate-middleware.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMiddleware = generateMiddleware;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Detect if project uses src/ directory structure
+ */
+function usesSrcDirectory(projectPath) {
+    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/)
+ */
+function generateMiddleware(projectPath) {
+    // 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/dist/generate-proxy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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)
+ */
+/**
+ * Generate proxy.ts file in the correct location (root or src/)
+ */
+export declare function generateProxy(projectPath: string): void;