@olane/o-server 0.7.2

package/README.md

@@ -0,0 +1,721 @@
+# @olane/o-server
+
+HTTP server entrypoint for Olane OS nodes. Exposes a node's `use` functionality via REST API.
+
+**TL;DR**: Add HTTP/REST endpoints to any Olane node. Perfect for web frontends, mobile apps, or external services that need HTTP access to your node's capabilities.
+
+## Installation
+
+```bash
+npm install @olane/o-server
+```
+
+## Quick Start
+
+Add HTTP endpoints to your Olane node:
+
+```typescript
+import { oServer } from '@olane/o-server';
+import { oLaneTool } from '@olane/o-lane';
+import { oAddress } from '@olane/o-core';
+
+// Create your node
+const myNode = new oLaneTool({
+  address: new oAddress('o://my-node'),
+  // ... other config
+});
+
+await myNode.start();
+
+// Add HTTP server
+const server = oServer({
+  node: myNode,
+  port: 3000
+});
+
+await server.start();
+// Server running on http://localhost:3000/api/v1
+```
+
+Now make HTTP calls to your node:
+
+```bash
+# Call the node's 'use' method via HTTP
+curl -X POST http://localhost:3000/api/v1/use \
+  -H "Content-Type: application/json" \
+  -d '{
+    "address": "o://analytics",
+    "method": "calculate_revenue",
+    "params": {"startDate": "2024-01-01", "endDate": "2024-03-31"}
+  }'
+```
+
+## How It Works
+
+`o-server` is a **simple HTTP wrapper** around a node's `use` method:
+
+```
+┌────────────────────────┐
+│  HTTP Client           │
+│  (Web, Mobile, etc.)   │
+└────────────────────────┘
+           ⬇ HTTP POST
+┌────────────────────────┐
+│  o-server              │
+│  • Translates request  │
+│  • Calls node.use()    │
+│  • Returns JSON        │
+└────────────────────────┘
+           ⬇ node.use(address, data)
+┌────────────────────────┐
+│  Your Olane Node       │
+│  • Routes to target    │
+│  • Executes method     │
+│  • Returns result      │
+└────────────────────────┘
+```
+
+**Key Point**: `o-server` does NOT contain or manage Olane OS. It's just an HTTP entrypoint into a node that participates in Olane OS.
+
+## API Endpoints
+
+### POST `/api/v1/use`
+
+Primary endpoint - calls the node's `use` method directly.
+
+**Request Body:**
+```json
+{
+  "address": "o://target/node",
+  "method": "method_name",
+  "params": { ... },
+  "id": "optional-request-id"
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/api/v1/use \
+  -H "Content-Type: application/json" \
+  -d '{
+    "address": "o://calculator",
+    "method": "add",
+    "params": {"a": 5, "b": 3}
+  }'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "result": 8
+  }
+}
+```
+
+---
+
+### POST `/api/v1/:address/:method`
+
+Convenience endpoint - REST-style URL structure.
+
+**Parameters:**
+- `address` (path): Target node address (without `o://` prefix)
+- `method` (path): Method name to call
+- `params` (body): Method parameters as JSON
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/api/v1/calculator/add \
+  -H "Content-Type: application/json" \
+  -d '{"a": 5, "b": 3}'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "result": 8
+  }
+}
+```
+
+---
+
+### POST `/api/v1/use/stream`
+
+Streaming endpoint (Server-Sent Events).
+
+**Request Body:**
+```json
+{
+  "address": "o://target/node",
+  "method": "method_name",
+  "params": { ... }
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/api/v1/use/stream \
+  -H "Content-Type: application/json" \
+  -d '{
+    "address": "o://analytics",
+    "method": "generate_report",
+    "params": {"format": "pdf"}
+  }'
+```
+
+**Response (SSE):**
+```
+data: {"type":"complete","result":{...}}
+```
+
+---
+
+### GET `/api/v1/health`
+
+Health check endpoint.
+
+**Example:**
+```bash
+curl http://localhost:3000/api/v1/health
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "status": "healthy",
+    "timestamp": 1704067200000,
+    "uptime": 3600.5
+  }
+}
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+import { oServer } from '@olane/o-server';
+
+const server = oServer({
+  // Required: Your Olane node
+  node: myNode,
+  
+  // Optional: Server port (default: 3000)
+  port: 8080,
+  
+  // Optional: Base path (default: '/api/v1')
+  basePath: '/api/v2',
+  
+  // Optional: CORS settings
+  cors: {
+    origin: 'https://example.com',
+    credentials: true
+  },
+  
+  // Optional: Authentication middleware
+  authenticate: async (req) => {
+    const token = req.headers.authorization;
+    return validateToken(token);
+  },
+  
+  // Optional: Enable debug logging (default: false)
+  debug: true
+});
+
+await server.start();
+```
+
+### Authentication
+
+Protect your endpoints with authentication:
+
+```typescript
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  authenticate: async (req) => {
+    // Validate JWT token
+    const token = req.headers.authorization?.split(' ')[1];
+    
+    if (!token) {
+      throw new Error('No token provided');
+    }
+    
+    const user = await verifyJWT(token);
+    return { userId: user.id, roles: user.roles };
+  }
+});
+
+// Now all requests require valid authentication
+```
+
+### CORS Configuration
+
+Enable cross-origin requests:
+
+```typescript
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  cors: {
+    origin: 'http://localhost:5173', // Your frontend URL
+    credentials: true,
+    allowedHeaders: ['Content-Type', 'Authorization']
+  }
+});
+```
+
+### Custom Routes
+
+Add custom routes alongside auto-generated endpoints:
+
+```typescript
+const server = oServer({ node: myNode, port: 3000 });
+
+// Add custom route
+server.app.get('/status', (req, res) => {
+  res.json({ status: 'operational' });
+});
+
+// Add custom middleware
+server.app.use((req, res, next) => {
+  console.log(`${req.method} ${req.path}`);
+  next();
+});
+
+await server.start();
+```
+
+## Common Use Cases
+
+### Use Case 1: Web Frontend Integration
+
+Expose your node to a React/Vue/Angular app:
+
+```typescript
+// backend/server.ts
+import { oServer } from '@olane/o-server';
+import { oLaneTool } from '@olane/o-lane';
+import { oAddress } from '@olane/o-core';
+
+const analyticsNode = new oLaneTool({
+  address: new oAddress('o://analytics'),
+  // ... config
+});
+
+await analyticsNode.start();
+
+const server = oServer({
+  node: analyticsNode,
+  port: 3000,
+  cors: { origin: 'http://localhost:5173' } // Vite dev server
+});
+
+await server.start();
+```
+
+```typescript
+// frontend/src/api.ts
+export async function analyzeRevenue(startDate: string, endDate: string) {
+  const response = await fetch('http://localhost:3000/api/v1/use', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      address: 'o://analytics',
+      method: 'calculate_revenue',
+      params: { startDate, endDate }
+    })
+  });
+  
+  const result = await response.json();
+  return result.data;
+}
+```
+
+### Use Case 2: Mobile App Backend
+
+Create a REST API for iOS/Android apps:
+
+```typescript
+import { oServer } from '@olane/o-server';
+
+const server = oServer({
+  node: myNode,
+  port: 8080,
+  authenticate: async (req) => {
+    // Validate Firebase auth token
+    const token = req.headers.authorization?.split(' ')[1];
+    const decodedToken = await admin.auth().verifyIdToken(token);
+    return { userId: decodedToken.uid };
+  }
+});
+
+await server.start();
+```
+
+### Use Case 3: Webhook Handler
+
+Receive webhooks from external services:
+
+```typescript
+import { oServer } from '@olane/o-server';
+import { oAddress } from '@olane/o-core';
+
+const server = oServer({ node: myNode, port: 3000 });
+
+// Stripe webhook
+server.app.post('/webhooks/stripe', async (req, res) => {
+  const event = req.body;
+  
+  // Process via your node
+  await myNode.use(
+    new oAddress('o://payments/processor'),
+    {
+      method: 'handle_payment',
+      params: { event }
+    }
+  );
+  
+  res.json({ received: true });
+});
+
+await server.start();
+```
+
+### Use Case 4: Internal API Gateway
+
+Gateway node that routes to other nodes:
+
+```typescript
+import { oServer } from '@olane/o-server';
+import { oLaneTool } from '@olane/o-lane';
+import { oAddress } from '@olane/o-core';
+
+// Create gateway node connected to network
+const gateway = new oLaneTool({
+  address: new oAddress('o://gateway'),
+  leader: new oAddress('o://leader'),
+  // ... config
+});
+
+await gateway.start();
+
+// Expose gateway via HTTP
+const server = oServer({
+  node: gateway,
+  port: 3000
+});
+
+await server.start();
+
+// Now clients can call ANY node in the network via HTTP
+// curl -X POST http://localhost:3000/api/v1/use \
+//   -d '{"address": "o://any/node/in/network", "method": "...", "params": {...}}'
+```
+
+## Error Handling
+
+`o-server` provides consistent error responses:
+
+```typescript
+// Success response
+{
+  "success": true,
+  "data": { ... }
+}
+
+// Error response
+{
+  "success": false,
+  "error": {
+    "code": "EXECUTION_ERROR",
+    "message": "Error message",
+    "details": { ... }
+  }
+}
+```
+
+**Common error codes:**
+- `INVALID_PARAMS` - Missing or invalid request parameters
+- `NODE_NOT_FOUND` - Target node address not found
+- `TOOL_NOT_FOUND` - Method doesn't exist on target node
+- `EXECUTION_ERROR` - Error during method execution
+- `TIMEOUT` - Request exceeded timeout limit
+- `UNAUTHORIZED` - Authentication failed
+
+**Custom error handling:**
+
+```typescript
+const server = oServer({ node: myNode, port: 3000 });
+
+server.app.use((err, req, res, next) => {
+  console.error('Server error:', err);
+  
+  res.status(err.status || 500).json({
+    success: false,
+    error: {
+      code: err.code || 'INTERNAL_ERROR',
+      message: err.message,
+      details: process.env.NODE_ENV === 'development' ? err.stack : undefined
+    }
+  });
+});
+```
+
+## Troubleshooting
+
+### Error: "Node is not running"
+
+**Cause:** Node not started before creating server.
+
+**Solution:**
+```typescript
+const myNode = new oLaneTool({ ... });
+await myNode.start(); // ← Make sure node is started
+
+const server = oServer({ node: myNode, port: 3000 });
+await server.start();
+```
+
+### Error: "Invalid address"
+
+**Cause:** Address format is incorrect.
+
+**Solution:**
+```bash
+# Correct - with o:// prefix
+curl -X POST http://localhost:3000/api/v1/use \
+  -d '{"address": "o://target", ...}'
+
+# Also correct - using convenience endpoint
+curl -X POST http://localhost:3000/api/v1/target/method \
+  -d '{"params": {...}}'
+```
+
+### Error: "CORS policy blocked"
+
+**Cause:** Cross-origin requests not configured.
+
+**Solution:**
+```typescript
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  cors: {
+    origin: 'http://localhost:5173', // Your frontend URL
+    credentials: true
+  }
+});
+```
+
+### High Latency
+
+**Cause:** Network overhead or inefficient routing.
+
+**Solutions:**
+1. Deploy o-server on same machine as the node
+2. Use o-server on a gateway node connected to the network
+3. Enable caching for frequently accessed data
+4. Consider using WebSocket transport for real-time needs
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import { oServer, ServerConfig, ServerInstance } from '@olane/o-server';
+import { oCore } from '@olane/o-core';
+
+const config: ServerConfig = {
+  node: myNode,
+  port: 3000,
+  basePath: '/api/v1',
+  cors: {
+    origin: 'https://example.com'
+  },
+  authenticate: async (req) => {
+    return { userId: '123' };
+  },
+  debug: true
+};
+
+const server: ServerInstance = oServer(config);
+await server.start();
+```
+
+## Production Deployment
+
+### Environment Variables
+
+```bash
+# .env
+PORT=8080
+BASE_PATH=/api/v1
+NODE_ENV=production
+LOG_LEVEL=info
+```
+
+### Docker Deployment
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+RUN npm run build
+
+EXPOSE 8080
+
+CMD ["node", "dist/index.js"]
+```
+
+### Health Checks
+
+```typescript
+const server = oServer({ node: myNode, port: 3000 });
+
+// Health check endpoint is built-in
+// GET /api/v1/health
+
+// For Kubernetes/Docker health checks:
+// livenessProbe:
+//   httpGet:
+//     path: /api/v1/health
+//     port: 3000
+```
+
+## Architecture Patterns
+
+### Pattern 1: Node-Specific Server
+
+One server per node (isolated services):
+
+```
+┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+│ o-server    │       │ o-server    │       │ o-server    │
+│ :3000       │       │ :3001       │       │ :3002       │
+└─────────────┘       └─────────────┘       └─────────────┘
+      ⬇                     ⬇                     ⬇
+┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+│ Analytics   │       │ CRM Node    │       │ Payment     │
+│ Node        │       │             │       │ Node        │
+└─────────────┘       └─────────────┘       └─────────────┘
+```
+
+**Best for:** Microservices architecture, team isolation
+
+---
+
+### Pattern 2: Gateway Server
+
+One server on a gateway node (unified API):
+
+```
+                ┌─────────────┐
+                │ o-server    │
+                │ :3000       │
+                └─────────────┘
+                      ⬇
+                ┌─────────────┐
+                │ Gateway     │
+                │ Node        │
+                └─────────────┘
+                      ⬇ connected to network
+        ┌──────────────┼──────────────┐
+        ⬇              ⬇              ⬇
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ Analytics   │ │ CRM Node    │ │ Payment     │
+│ Node        │ │             │ │ Node        │
+└─────────────┘ └─────────────┘ └─────────────┘
+```
+
+**Best for:** Unified API, single entry point, centralized auth
+
+---
+
+### Pattern 3: Load Balanced
+
+Multiple servers for high availability:
+
+```
+                ┌─────────────┐
+                │ Load        │
+                │ Balancer    │
+                └─────────────┘
+                       ⬇
+        ┌──────────────┼──────────────┐
+        ⬇              ⬇              ⬇
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ o-server 1  │ │ o-server 2  │ │ o-server 3  │
+│ :3000       │ │ :3000       │ │ :3000       │
+└─────────────┘ └─────────────┘ └─────────────┘
+        └──────────────┼──────────────┘
+                       ⬇
+              ┌─────────────────┐
+              │   Gateway Node  │
+              │   (shared)      │
+              └─────────────────┘
+```
+
+**Best for:** High traffic, 99.9%+ uptime requirements
+
+## Related Packages
+
+- **[@olane/o-core](/packages/o-core)** - Core types and `use` method
+- **[@olane/o-node](/packages/o-node)** - Build tool nodes
+- **[@olane/o-lane](/packages/o-lane)** - Intent-driven nodes
+
+## Examples
+
+Complete examples:
+
+```typescript
+// Basic server
+const server = oServer({ node: myNode, port: 3000 });
+await server.start();
+
+// With authentication
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  authenticate: async (req) => {
+    const token = req.headers.authorization;
+    return await validateJWT(token);
+  }
+});
+
+// With rate limiting
+import rateLimit from 'express-rate-limit';
+
+const server = oServer({ node: myNode, port: 3000 });
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100
+});
+
+server.app.use('/api/v1', limiter);
+await server.start();
+```
+
+## License
+
+ISC
+
+## Support
+
+- **Documentation**: [https://docs.olane.com](https://docs.olane.com)
+- **GitHub**: [https://github.com/olane-labs/olane](https://github.com/olane-labs/olane)
+- **Issues**: [https://github.com/olane-labs/olane/issues](https://github.com/olane-labs/olane/issues)

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { oServer } from './o-server.js';
+export { ServerConfig, ServerInstance, AuthenticateFunction, } from './interfaces/server-config.interface.js';
+export { ErrorResponse, SuccessResponse, } from './interfaces/response.interface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,aAAa,EACb,eAAe,GAChB,MAAM,oCAAoC,CAAC"}

package/dist/src/index.js

@@ -0,0 +1 @@
+export { oServer } from './o-server.js';

package/dist/src/interfaces/response.interface.d.ts

@@ -0,0 +1,14 @@
+export interface SuccessResponse<T = any> {
+    success: true;
+    data: T;
+}
+export interface ErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+}
+export type ApiResponse<T = any> = SuccessResponse<T> | ErrorResponse;
+//# sourceMappingURL=response.interface.d.ts.map

package/dist/src/interfaces/response.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/response.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACT;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,CAAC;CACH;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC"}

package/dist/src/interfaces/response.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/src/interfaces/server-config.interface.d.ts

@@ -0,0 +1,31 @@
+import { oCore } from '@olane/o-core';
+import { Request } from 'express';
+import { CorsOptions } from 'cors';
+export interface AuthUser {
+    userId?: string;
+    [key: string]: any;
+}
+export type AuthenticateFunction = (req: Request) => Promise<AuthUser>;
+export interface ServerConfig {
+    /** Node instance (any oCore-based node with 'use' method) */
+    node: oCore;
+    /** Server port (default: 3000) */
+    port?: number;
+    /** Base path for API routes (default: '/api/v1') */
+    basePath?: string;
+    /** CORS configuration */
+    cors?: CorsOptions;
+    /** Authentication middleware */
+    authenticate?: AuthenticateFunction;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export interface ServerInstance {
+    /** Express app instance */
+    app: any;
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=server-config.interface.d.ts.map

package/dist/src/interfaces/server-config.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/server-config.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvE,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,KAAK,CAAC;IAEZ,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,yBAAyB;IACzB,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB,gCAAgC;IAChC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAEpC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,GAAG,EAAE,GAAG,CAAC;IAET,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/src/interfaces/server-config.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/src/middleware/auth.d.ts

@@ -0,0 +1,11 @@
+import { Request, Response, NextFunction } from 'express';
+import { AuthenticateFunction, AuthUser } from '../interfaces/server-config.interface.js';
+declare global {
+    namespace Express {
+        interface Request {
+            user?: AuthUser;
+        }
+    }
+}
+export declare function authMiddleware(authenticate: AuthenticateFunction): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACT,MAAM,0CAA0C,CAAC;AAElD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,QAAQ,CAAC;SACjB;KACF;CACF;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,oBAAoB,SAC5C,OAAO,OAAO,QAAQ,QAAQ,YAAY,mBAe9D"}

package/dist/src/middleware/auth.js

@@ -0,0 +1,18 @@
+export function authMiddleware(authenticate) {
+    return async (req, res, next) => {
+        try {
+            const user = await authenticate(req);
+            req.user = user;
+            next();
+        }
+        catch (error) {
+            res.status(401).json({
+                success: false,
+                error: {
+                    code: 'UNAUTHORIZED',
+                    message: error.message || 'Authentication failed',
+                },
+            });
+        }
+    };
+}

package/dist/src/middleware/error-handler.d.ts

@@ -0,0 +1,8 @@
+import { Request, Response, NextFunction } from 'express';
+export interface OlaneError extends Error {
+    code?: string;
+    status?: number;
+    details?: any;
+}
+export declare function errorHandler(err: OlaneError, req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/src/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,MAAM,WAAW,UAAW,SAAQ,KAAK;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,QAenB"}

package/dist/src/middleware/error-handler.js

@@ -0,0 +1,13 @@
+export function errorHandler(err, req, res, next) {
+    console.error('[o-server] Error:', err);
+    const status = err.status || 500;
+    const errorResponse = {
+        success: false,
+        error: {
+            code: err.code || 'INTERNAL_ERROR',
+            message: err.message || 'An internal error occurred',
+            details: process.env.NODE_ENV === 'development' ? err.details : undefined,
+        },
+    };
+    res.status(status).json(errorResponse);
+}

package/dist/src/o-server.d.ts

@@ -0,0 +1,3 @@
+import { ServerConfig, ServerInstance } from './interfaces/server-config.interface.js';
+export declare function oServer(config: ServerConfig): ServerInstance;
+//# sourceMappingURL=o-server.d.ts.map

package/dist/src/o-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-server.d.ts","sourceRoot":"","sources":["../../src/o-server.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,YAAY,EACZ,cAAc,EACf,MAAM,yCAAyC,CAAC;AAQjD,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CA4O5D"}

package/dist/src/o-server.js

@@ -0,0 +1,195 @@
+import express from 'express';
+import cors from 'cors';
+import { errorHandler } from './middleware/error-handler.js';
+import { authMiddleware } from './middleware/auth.js';
+import { ServerLogger } from './utils/logger.js';
+import { oAddress } from '@olane/o-core';
+export function oServer(config) {
+    const { node, port = 3000, basePath = '/api/v1', cors: corsConfig, authenticate, debug = false, } = config;
+    const app = express();
+    const logger = new ServerLogger(debug);
+    let server = null;
+    // Middleware
+    app.use(express.json());
+    if (corsConfig) {
+        app.use(cors(corsConfig));
+    }
+    // Optional authentication
+    if (authenticate) {
+        app.use(basePath, authMiddleware(authenticate));
+    }
+    // Health check endpoint
+    app.get(`${basePath}/health`, (req, res) => {
+        res.json({
+            success: true,
+            data: {
+                status: 'healthy',
+                timestamp: Date.now(),
+                uptime: process.uptime(),
+            },
+        });
+    });
+    // Primary endpoint - POST /api/v1/use
+    // This is the main entrypoint that wraps the node's 'use' method
+    app.post(`${basePath}/use`, async (req, res, next) => {
+        try {
+            const { address: addressStr, method, params, id } = req.body;
+            if (!addressStr) {
+                const error = new Error('Address is required');
+                error.code = 'INVALID_PARAMS';
+                error.status = 400;
+                throw error;
+            }
+            logger.debugLog(`Calling use with address ${addressStr}, method: ${method}`);
+            const address = new oAddress(addressStr);
+            const result = await node.use(address, {
+                method,
+                params,
+                id,
+            });
+            const response = {
+                success: true,
+                data: result.result,
+            };
+            res.json(response);
+        }
+        catch (error) {
+            handleOlaneError(error, next);
+        }
+    });
+    // Convenience endpoint for tool calls - POST /api/v1/:address/:method
+    // This provides a more REST-like interface but still uses the node's 'use' method
+    app.post(`${basePath}/:address/:method`, async (req, res, next) => {
+        try {
+            const { address: addressParam, method } = req.params;
+            const params = req.body;
+            logger.debugLog(`Calling method ${method} on ${addressParam} with params:`, params);
+            const address = new oAddress(`o://${addressParam}`);
+            const result = await node.use(address, {
+                method,
+                params,
+            });
+            const response = {
+                success: true,
+                data: result.result,
+            };
+            res.json(response);
+        }
+        catch (error) {
+            handleOlaneError(error, next);
+        }
+    });
+    // Streaming endpoint - POST /api/v1/use/stream
+    app.post(`${basePath}/use/stream`, async (req, res, next) => {
+        try {
+            const { address: addressStr, method, params } = req.body;
+            if (!addressStr) {
+                const error = new Error('Address is required');
+                error.code = 'INVALID_PARAMS';
+                error.status = 400;
+                throw error;
+            }
+            logger.debugLog(`Streaming use call to ${addressStr}, method: ${method}`);
+            // Set headers for Server-Sent Events
+            res.setHeader('Content-Type', 'text/event-stream');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            const address = new oAddress(addressStr);
+            try {
+                // TODO: Implement actual streaming support when available
+                // For now, execute and return result
+                const result = await node.use(address, {
+                    method,
+                    params,
+                });
+                res.write(`data: ${JSON.stringify({
+                    type: 'complete',
+                    result: result.result,
+                })}\n\n`);
+                res.end();
+            }
+            catch (error) {
+                res.write(`data: ${JSON.stringify({
+                    type: 'error',
+                    error: {
+                        code: error.code || 'EXECUTION_ERROR',
+                        message: error.message,
+                    },
+                })}\n\n`);
+                res.end();
+            }
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // Error handling middleware (must be last)
+    app.use(errorHandler);
+    // Helper function to convert Olane errors to HTTP errors
+    function handleOlaneError(error, next) {
+        const olaneError = new Error(error.message || 'Unknown error');
+        // Map common error scenarios
+        if (error.code === 'NODE_NOT_FOUND') {
+            olaneError.code = 'NODE_NOT_FOUND';
+            olaneError.status = 404;
+        }
+        else if (error.code === 'TOOL_NOT_FOUND') {
+            olaneError.code = 'TOOL_NOT_FOUND';
+            olaneError.status = 404;
+        }
+        else if (error.code === 'INVALID_PARAMS') {
+            olaneError.code = 'INVALID_PARAMS';
+            olaneError.status = 400;
+        }
+        else if (error.code === 'TIMEOUT') {
+            olaneError.code = 'TIMEOUT';
+            olaneError.status = 504;
+        }
+        else if (error.message?.includes('not found')) {
+            olaneError.code = 'NODE_NOT_FOUND';
+            olaneError.status = 404;
+        }
+        else {
+            olaneError.code = 'EXECUTION_ERROR';
+            olaneError.status = 500;
+        }
+        olaneError.details = error.details || error.stack;
+        next(olaneError);
+    }
+    // Server instance
+    const instance = {
+        app,
+        async start() {
+            return new Promise((resolve, reject) => {
+                try {
+                    server = app.listen(port, () => {
+                        logger.log(`Server running on http://localhost:${port}${basePath}`);
+                        resolve();
+                    });
+                    server.on('error', reject);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        },
+        async stop() {
+            return new Promise((resolve, reject) => {
+                if (!server) {
+                    resolve();
+                    return;
+                }
+                server.close((err) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        logger.log('Server stopped');
+                        resolve();
+                    }
+                });
+            });
+        },
+    };
+    return instance;
+}

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare class ServerLogger {
+    private debug;
+    constructor(debug?: boolean);
+    log(...args: any[]): void;
+    error(...args: any[]): void;
+    debugLog(...args: any[]): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAU;gBAEX,KAAK,GAAE,OAAe;IAIlC,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAIlB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;IAIpB,QAAQ,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE;CAKxB"}

package/dist/src/utils/logger.js

@@ -0,0 +1,16 @@
+export class ServerLogger {
+    constructor(debug = false) {
+        this.debug = debug;
+    }
+    log(...args) {
+        console.log('[o-server]', ...args);
+    }
+    error(...args) {
+        console.error('[o-server ERROR]', ...args);
+    }
+    debugLog(...args) {
+        if (this.debug) {
+            console.log('[o-server DEBUG]', ...args);
+        }
+    }
+}

package/dist/test/ai.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ai.spec.d.ts.map

package/dist/test/ai.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.spec.d.ts","sourceRoot":"","sources":["../../test/ai.spec.ts"],"names":[],"mappings":""}

package/dist/test/ai.spec.js

@@ -0,0 +1,19 @@
+import { NodeState, oAddress } from '@olane/o-core';
+import { oLaneTool } from '@olane/o-lane';
+import { expect } from 'chai';
+describe('in-process @memory', () => {
+    it('should be able to start a single node with no leader', async () => {
+        const node = new oLaneTool({
+            address: new oAddress('o://test'),
+            leader: null,
+            parent: null,
+        });
+        await node.start();
+        expect(node.state).to.equal(NodeState.RUNNING);
+        const transports = node.transports;
+        // expect(transports.length).to.equal(1);
+        // expect(transports[0].toString()).to.contain('/memory');
+        await node.stop();
+        expect(node.state).to.equal(NodeState.STOPPED);
+    });
+});

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@olane/o-server",
+  "version": "0.7.2",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "aegir test",
+    "test:node": "aegir test -t node",
+    "test:browser": "aegir test -t browser",
+    "dev": "DEBUG=o-protocol:* npx tsx src/tests/index.ts",
+    "build": "tsc",
+    "deep:clean": "rm -rf node_modules && rm package-lock.json",
+    "start:prod": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "update:lib": "npm install @olane/o-core@latest",
+    "update:peers": "npm install @olane/o-core@latest @olane/o-config@latest @olane/o-protocol@latest @olane/o-tool@latest --save-peer",
+    "lint": "eslint src/**/*.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olane-labs/olane.git"
+  },
+  "author": "oLane Inc.",
+  "license": "ISC",
+  "description": "HTTP server entrypoint for Olane OS nodes - exposes node's 'use' functionality via REST API",
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.29.0",
+    "@tsconfig/node20": "^20.1.6",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.34.1",
+    "@typescript-eslint/parser": "^8.34.1",
+    "aegir": "^47.0.21",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.6",
+    "eslint-plugin-prettier": "^5.5.0",
+    "globals": "^16.2.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "tsx": "^4.20.3",
+    "typescript": "5.4.5"
+  },
+  "peerDependencies": {
+    "@olane/o-config": "^0.7.1",
+    "@olane/o-core": "^0.7.1",
+    "@olane/o-protocol": "^0.7.1",
+    "@olane/o-tool": "^0.7.1"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "debug": "^4.4.1",
+    "dotenv": "^16.5.0",
+    "express": "^4.19.2"
+  }
+}