npm package: @navada25/edge-sdk
Description: Official SDK for the NAVADA Edge Network — distributed AI infrastructure with Cloudflare, Docker, Azure, and AI services
Author: Leslie Akpareva
Latest version: 1.0.0

# @navada/edge-sdk

Official SDK for the **NAVADA Edge Network** — a distributed AI infrastructure connecting physical nodes, cloud services, and AI models through a single unified API.

Zero dependencies. Works with npm, pnpm, and yarn. Node.js 18+.

```
pnpm add @navada/edge-sdk
```

## What is NAVADA Edge Network?

NAVADA Edge is a distributed computing mesh that connects physical servers, cloud VMs, and managed services over an encrypted Tailscale VPN:

```
                         TAILSCALE VPN MESH
    ┌──────────────────────────────────────────────────┐
    │                                                    │
    │  [Node 1]          [Node 2]         [Node 3]      │
    │  Production         Database         Monitoring    │
    │  MCP Server         Postgres         Telegram Bot  │
    │  Dashboard          OpenCode         Lucas CTO     │
    │  Registry                                          │
    │  YOLO AI            [Node 4]                       │
    │                     Docker Infra                   │
    │                     Portainer                      │
    │                     Grafana                        │
    │                                                    │
    └──────────────────────────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         [Cloudflare]  [Azure]     [AI APIs]
         R2 Storage    n8n         OpenAI
         Flux (free)   Container   HuggingFace
         Stream CDN    Apps        YOLO
         Tunnel/DNS
```

The SDK gives you one `require()` to access everything.

## Quick Start

```js
const navada = require('@navada/edge-sdk');

// Configure (choose one):

// Option A: environment variables (recommended for Docker)
// Set NAVADA_ASUS, NAVADA_MCP, etc. in your .env or container env

// Option B: programmatic
navada.init({
  asus: '10.0.0.1',
  mcp: 'http://10.0.0.1:8811',
  dashboard: 'http://10.0.0.1:7900',
  registry: 'http://10.0.0.1:5000',
});

// Use it
const status = await navada.network.ping();
const tools = await navada.mcp.tools();
const images = await navada.registry.catalog();
```

## Configuration

The SDK reads from environment variables. Copy `.env.example` to `.env`:

```bash
cp node_modules/@navada/edge-sdk/.env.example .env
```

### Environment Variables

| Variable | Module | Description |
|----------|--------|-------------|
| `SERVICE_NAME` | `config` | Your service name |
| `NAVADA_NODE` | `config` | Which node this runs on |
| **Nodes** | | |
| `NAVADA_ASUS` | `network` | Node 1 Tailscale IP |
| `NAVADA_HP` | `network` | Node 2 Tailscale IP |
| `NAVADA_EC2` | `network` | Node 3 Tailscale IP |
| `NAVADA_ORACLE` | `network` | Node 4 Tailscale IP |
| **Services** | | |
| `NAVADA_MCP` | `mcp` | MCP server URL (e.g. `http://10.0.0.1:8811`) |
| `NAVADA_DASHBOARD` | `dashboard` | Command Dashboard URL |
| `NAVADA_REGISTRY` | `registry` | Docker registry URL |
| `NAVADA_LUCAS` | `lucas` | Lucas CTO MCP URL |
| `NAVADA_PORTAINER` | `network` | Portainer URL |
| **Database** | | |
| `NAVADA_PG_HOST` | `db` | Postgres host |
| `NAVADA_PG_PORT` | `db` | Postgres port (default: 5432) |
| `NAVADA_PG_DB` | `db` | Database name |
| `NAVADA_PG_USER` | `db` | Username |
| `NAVADA_PG_PASS` | `db` | Password |
| **Auth** | | |
| `MCP_API_KEY` | `mcp` | MCP server API key |
| `DASHBOARD_API_KEY` | `dashboard` | Dashboard API key |
| **Cloudflare** | | |
| `CLOUDFLARE_ACCOUNT_ID` | `cloudflare.*` | Account ID |
| `CLOUDFLARE_API_TOKEN` | `cloudflare.*` | API token |
| `CLOUDFLARE_R2_BUCKET` | `cloudflare.r2` | Default R2 bucket |
| `CLOUDFLARE_STREAM_SUBDOMAIN` | `cloudflare.stream` | Stream subdomain |
| `CLOUDFLARE_DOMAIN` | `network` | Your domain |
| `CLOUDFLARE_ZONE_ID` | `cloudflare.dns` | DNS zone ID |
| **Azure** | | |
| `AZURE_N8N_URL` | `azure.n8n` | n8n Container App URL |
| `AZURE_N8N_RESOURCE_GROUP` | `azure.n8n` | Resource group |
| `AZURE_N8N_APP_NAME` | `azure.n8n` | App name |
| **AI** | | |
| `NAVADA_YOLO` | `ai.yolo` | YOLO service URL |
| `HF_TOKEN` | `ai.huggingface` | HuggingFace token |
| `OPENAI_API_KEY` | `ai.openai` | OpenAI key |

### Programmatic Config

```js
const navada = require('@navada/edge-sdk');

navada.init({
  asus: '10.0.0.1',
  hp: '10.0.0.2',
  ec2: '10.0.0.3',
  oracle: '10.0.0.4',
  mcp: 'http://10.0.0.1:8811',
  dashboard: 'http://10.0.0.1:7900',
  registry: 'http://10.0.0.1:5000',
  cfAccountId: 'your-cf-account-id',
  cfApiToken: 'your-cf-token',
  openaiKey: 'sk-...',
});
```

You can mix env vars and `init()` — `init()` values override env vars.

## API Reference

### `navada.init(config)`

Override any config value programmatically.

### `navada.network`

```js
await navada.network.ping()     // Ping all configured nodes + cloud services
await navada.network.status()   // Full status from Command Dashboard
navada.network.nodes             // { asus: { ip, role }, hp: {...}, ... }
```

### `navada.mcp`

Call tools on the MCP server (Model Context Protocol).

```js
await navada.mcp.tools()                    // List available tools
await navada.mcp.call('tool_name', {args})  // Execute a tool
```

### `navada.lucas`

Run commands on remote nodes via Lucas CTO MCP.

```js
await navada.lucas.exec('docker ps')             // Bash on EC2
await navada.lucas.ssh('hp', 'df -h')            // SSH to any node
await navada.lucas.docker('container', 'cmd')    // Docker exec
await navada.lucas.deploy('name', 'node')        // Deploy container
await navada.lucas.readFile('/path/to/file')      // Read file
await navada.lucas.writeFile('/path', 'content')  // Write file
await navada.lucas.listFiles('/dir')              // List files
await navada.lucas.networkStatus()                // Full network status
```

### `navada.dashboard`

Register services and log activity to the Command Center.

```js
await navada.dashboard.register(3000)                  // Register this service
await navada.dashboard.activity('deploy', 'v2 live')   // Log an event
```

### `navada.db`

Query Postgres. Requires `pg` package (`npm install pg`).

```js
await navada.db.query('SELECT NOW()')
await navada.db.query('SELECT * FROM users WHERE id = $1', [42])
const client = await navada.db.getClient()  // For transactions
await navada.db.close()                      // Close pool
```

### `navada.registry`

Query the private Docker registry.

```js
await navada.registry.catalog()          // ['my-api', 'dashboard', ...]
await navada.registry.tags('my-api')     // ['latest', 'v2']
```

### `navada.opencode`

Check OpenCode instances on each node.

```js
await navada.opencode.status('asus')   // { node, online, status }
await navada.opencode.statusAll()       // All nodes
```

### `navada.cloudflare.r2`

Cloudflare R2 object storage.

```js
await navada.cloudflare.r2.buckets()                            // List buckets
await navada.cloudflare.r2.list('images/')                      // List objects
await navada.cloudflare.r2.upload('key', buffer, 'image/png')   // Upload
await navada.cloudflare.r2.upload('key', '/path/to/file.jpg')   // Upload from file
await navada.cloudflare.r2.delete('key')                        // Delete
navada.cloudflare.r2.publicUrl('key')                            // Get public URL
```

### `navada.cloudflare.flux`

Free AI image generation via Cloudflare Workers AI (Flux model).

```js
const { buffer, size } = await navada.cloudflare.flux.generate('a futuristic city')
await navada.cloudflare.flux.generate('logo', { width: 512, height: 512, savePath: './out.png' })
const { key, url } = await navada.cloudflare.flux.generateAndStore('prompt')  // Generate + upload to R2
```

### `navada.cloudflare.stream`

Cloudflare Stream video CDN.

```js
await navada.cloudflare.stream.list()                        // All videos
await navada.cloudflare.stream.uploadFromUrl(url, 'Title')   // Upload from URL
await navada.cloudflare.stream.get(videoId)                  // Video info
await navada.cloudflare.stream.delete(videoId)               // Delete
navada.cloudflare.stream.playbackUrl(videoId)                 // HLS URL
navada.cloudflare.stream.embedHtml(videoId)                   // Embed iframe
```

### `navada.cloudflare.tunnel`

```js
await navada.cloudflare.tunnel.list()        // List active tunnels
await navada.cloudflare.tunnel.get(id)       // Tunnel details
```

### `navada.cloudflare.dns`

```js
await navada.cloudflare.dns.list()                            // All records
await navada.cloudflare.dns.list('CNAME')                     // Filter by type
await navada.cloudflare.dns.create('CNAME', 'app', 'target')  // Create record
```

### `navada.cloudflare.trace(url)`

Trace a request through Cloudflare WAF/rules.

```js
await navada.cloudflare.trace('https://your-domain.com')
```

### `navada.azure.n8n`

Manage n8n on Azure Container Apps.

```js
await navada.azure.n8n.health()    // Health check
navada.azure.n8n.restart()          // Restart via Azure CLI
navada.azure.n8n.url                // Get URL
```

### `navada.ai.yolo`

YOLOv8 object detection running on your Edge node.

```js
await navada.ai.yolo.health()                      // Service status
await navada.ai.yolo.model()                       // Model info + classes
await navada.ai.yolo.detect('/path/to/image.jpg')  // Detection JSON
const { buffer, detections } = await navada.ai.yolo.detectImage('/path/to/image.jpg')  // Annotated image
```

### `navada.ai.huggingface`

HuggingFace Inference API. Qwen Coder is free.

```js
await navada.ai.huggingface.qwen('Write a REST API for user auth')  // Qwen Coder 32B
await navada.ai.huggingface.inference('model-name', 'input')         // Any HF model
```

### `navada.ai.openai`

OpenAI API (GPT, DALL-E).

```js
await navada.ai.openai.chat('What is the ISA allowance?')          // GPT-4o-mini
await navada.ai.openai.chat(messages, { model: 'gpt-4o' })         // Custom model
await navada.ai.openai.image('a futuristic server room')           // DALL-E 3
```

### `navada.request(url, opts)` / `navada.requestMultipart(url, fields, file, opts)`

Low-level HTTP helpers. Zero dependencies. Used internally, exposed for custom calls.

```js
const r = await navada.request('http://any-service/api', {
  method: 'POST',
  body: { key: 'value' },
  headers: { 'Authorization': 'Bearer token' },
  timeout: 5000,
});
console.log(r.status, r.data);
```

## Docker Integration

The SDK is designed for Docker-first workflows. In your `docker-compose.yml`:

```yaml
services:
  my-api:
    build: .
    env_file: .env
    ports:
      - "3000:3000"
```

Your `.env` contains all NAVADA network config. The SDK reads it automatically via `process.env`.

## Security

- **Never commit `.env` files** — add `.env` to `.gitignore`
- **Rotate API keys** regularly — the SDK reads fresh from env on each call
- **Use Tailscale** — nodes communicate over encrypted WireGuard VPN
- **Scope Cloudflare tokens** — create per-service API tokens with minimal permissions
- **Audit logs** — use `navada.dashboard.activity()` to log all operations

## Optional Dependencies

The SDK has **zero required dependencies**. Everything uses Node.js builtins.

**Postgres** requires the `pg` package:

```bash
pnpm add pg
# or
npm install pg
```

If `pg` is not installed, calling `navada.db.*` throws: `pg not installed. Run: npm install pg`

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `npm test`
5. Submit a pull request

## License

MIT - Leslie Akpareva / NAVADA