AI Control Plane SDK - Node.js

Easy integration for autonomous runtime control in your microservices. The SDK automatically tracks API performance and receives intelligent runtime configurations from the AI Control Plane.

Installation

npm install neuralcontrol

Links

• GitHub Repository: https://github.com/Ayush-soni-12/AI_CONTROL_PLANE
• npm Package: https://www.npmjs.com/package/neuralcontrol

For more information, documentation, and examples, visit the GitHub repository.

What Does This SDK Do?

The AI Control Plane SDK provides:

1. Secure API Key Authentication: All operations are authenticated with your API key
2. Automatic Performance Tracking: Monitors API latency and success/failure rates
3. Intelligent Runtime Configuration: Receives AI-driven decisions for caching, circuit breaking, and more
4. Tenant ID Generation: Creates unique identifiers for multi-tenant applications
5. Express Middleware: Easy integration with Express.js applications

The SDK sends performance metrics to the AI Control Plane, which analyzes patterns and returns intelligent configuration decisions to optimize your service automatically.

Quick Start (5 minutes)

0. Get Your API Key

⚠️ IMPORTANT: API key authentication is now required for all SDK operations.

1. Sign up at your Control Plane dashboard (e.g., https://neuralcontrol.online/dashboard/api-keys)
2. Navigate to API Keys page
3. Click "Generate New Key"
4. Copy your API key

1. Generate Tenant ID

Generate a unique tenant ID using OpenSSL:

openssl rand -hex 16

This will output a random 32-character hexadecimal string like: bfc3aed7948e46fafacac26faf8b3159

💡 Tip: Save this tenant ID in your environment variables or configuration file. Each service instance or user should have a unique tenant ID.

2. Initialize SDK with API Key

import ControlPlaneSDK from "neuralcontrol";
import dotenv from "dotenv";

dotenv.config();

const controlPlane = new ControlPlaneSDK({
  apiKey: process.env.CONTROL_PLANE_API_KEY, // ⚠️ REQUIRED
  tenantId: process.env.TENANT_ID, // ⚠️ REQUIRED - Generate using: openssl rand -hex 16
  serviceName: "my-service",
  controlPlaneUrl:
    process.env.CONTROL_PLANE_URL || "https://api.neuralcontrol.online",
});

// Pre-warm config for known endpoints (Recommended for 0ms latency overlay)
await controlPlane.initialize(["/products", "/products/:id?", "/login"]);

3. Use Middleware (Automatic Tracking)

Real Example from Demo Service:

import express from "express";
import ControlPlaneSDK from "neuralcontrol";
import dotenv from "dotenv";

dotenv.config();

const app = express();
const controlPlane = new ControlPlaneSDK({
  apiKey: process.env.CONTROL_PLANE_API_KEY, // Required
  tenantId: process.env.TENANT_ID, // Required - Generate with: openssl rand -hex 16
  serviceName: "demo-service",
  controlPlaneUrl:
    process.env.CONTROL_PLANE_URL || "https://api.neuralcontrol.online",
});

// Example: Product API with automatic tracking
app.get(
  "/products/:id?",
  controlPlane.middleware("/products"),
  async (req, res) => {
    const { id } = req.params;

    // Simulate database delay
    await new Promise((resolve) => setTimeout(resolve, 100));

    if (id) {
      // Get single product
      const product = { id: parseInt(id), name: "Laptop", price: 999 };
      res.json({ product });
    } else {
      // Get all products
      const products = [
        { id: 1, name: "Laptop", price: 999 },
        { id: 2, name: "Phone", price: 699 },
      ];
      res.json({ products });
    }
  },
);

// Start server and initialize SDK
const PORT = process.env.PORT || 3001;
app.listen(PORT, async () => {
  console.log(`Server running on http://localhost:${PORT}`);

  // Initialize Control Plane SDK with known endpoints
  await controlPlane.initialize(["/products", "/products/:id?"]);
});

What happens automatically:

• ✅ Tracks request latency
• ✅ Tracks success/failure status
• ✅ Sends metrics to Control Plane with API key authentication
• ✅ Receives runtime configuration (caching, circuit breaker decisions)
• ✅ Makes config available in req.controlPlane

API Authentication

Overview

All SDK operations require API key authentication. The SDK automatically includes your API key in the Authorization header for all requests to the Control Plane.

Getting an API Key

1. Sign up at your Control Plane dashboard
2. Navigate to the API Keys page
3. Click "Generate New Key"
4. Copy and securely store your API key

Authentication Flow

SDK Request → Authorization: Bearer <api_key> → Control Plane
                                                      ↓
                                                 Validates Key
                                                      ↓
                                              Associates with User
                                                      ↓
                                               Stores Signal

Error Handling

The SDK handles authentication errors gracefully:

Missing API Key:

// ⚠️ Warning logged to console
const controlPlane = new ControlPlaneSDK({
  serviceName: "my-service",
});
// Console: [ControlPlane] ⚠️ No API key provided. Please initialize the SDK with an API key.

Invalid API Key:

• Requests will fail silently (SDK doesn't crash your service)
• Errors logged to console
• Signals won't be tracked

Best Practices:

1. Use Environment Variables

   apiKey: process.env.CONTROL_PLANE_API_KEY;

2. Never Commit API Keys

   • Add .env to .gitignore
   • Use .env.example for documentation

3. Rotate Keys Regularly

   • Generate new keys periodically
   • Delete old keys from dashboard

4. Monitor Key Usage

   • Check "Last Used" timestamp in dashboard
   • Deactivate unused keys

API Reference

middleware(endpoint)

Express middleware for automatic tracking.

Example:

app.get("/products", controlPlane.middleware("/products"), (req, res) => {
  // Config available in req.controlPlane
});

Use Cases

Automatic Caching

app.get("/products", controlPlane.middleware("/products"), async (req, res) => {
  // Check cache
  if (req.controlPlane.shouldCache && cache.products) {
    return res.json(cache.products);
  }

  // Fetch from database
  const products = await db.getProducts();

  // Cache if enabled
  if (req.controlPlane.shouldCache) {
    cache.products = products;
  }

  res.json(products);
});

Circuit Breaker

app.get(
  "/external-api",
  controlPlane.middleware("/external-api"),
  async (req, res) => {
    // Skip if circuit breaker active
    if (req.controlPlane.shouldSkip) {
      return res.json({ data: cachedData || [] });
    }

    // Call external API
    const data = await externalAPI.getData();
    res.json(data);
  },
);

Current Features

This SDK currently provides:

• ✅ API Key Authentication - Secure authentication for all SDK operations
• ✅ Performance Tracking - Latency and success/error rate monitoring
• ✅ Runtime Configuration - AI-driven decisions from Control Plane
• ✅ Express Middleware - Automatic tracking with zero code changes
• ✅ Tenant ID Generation - Multi-tenant application support
• ✅ Configuration Caching - Reduces Control Plane load
• ✅ Graceful Error Handling - Fails silently without crashing your service

Requirements

• Node.js >= 18.0.0
• Express.js (for middleware usage)

Support

For issues, questions, or contributions, please visit the GitHub repository.

License

MIT