@elaraai/e3-api-server

HTTP server for e3 repositories.

Installation

npm install @elaraai/e3-api-server

Overview

REST API server exposing e3-core operations over HTTP. Uses BEAST2 binary serialization for efficient request/response encoding.

Supports two modes:

• Single-repo mode: Serve one repository, accessed via /repos/default
• Multi-repo mode: Serve multiple repositories from a directory, accessed via /repos/:name

CLI Usage

# Single repository mode
e3-api-server --repo /path/to/repo
e3-api-server --repo /path/to/repo --port 8080 --cors

# Multi-repository mode (serves repos from subdirectories)
e3-api-server --repos /path/to/repos-dir

# With OIDC authentication
e3-api-server --repo /path/to/repo --oidc

# Custom port and host
e3-api-server --repo /path/to/repo --port 8080 --host 0.0.0.0

CLI Options

| Option | Description | |--------|-------------| | --repo <path> | Single repository mode - serve one repo at /repos/default | | --repos <dir> | Multi-repo mode - serve repos from subdirectories | | -p, --port <port> | HTTP port (default: 3000) | | -H, --host <host> | Bind address (default: localhost) | | --cors | Enable CORS for cross-origin requests | | --oidc | Enable built-in OIDC authentication provider | | --token-expiry <duration> | Access token expiry, e.g., "5s", "15m", "1h" (default: 1h) | | --refresh-token-expiry <duration> | Refresh token expiry, e.g., "7d", "90d" (default: 90d) |

Programmatic Usage

Single Repository (Embedded Server)

For embedding in applications like VS Code extensions:

import { createServer } from '@elaraai/e3-api-server';

// createServer is async
const server = await createServer({
  singleRepoPath: '/path/to/repo',
  port: 3000,
  host: 'localhost',
  cors: true,  // Enable for webview/cross-origin access
});

await server.start();
console.log(`Server listening on http://localhost:${server.port}`);
console.log('Access repository via: /repos/default');

// Graceful shutdown
await server.stop();

Multi-Repository Mode

For serving multiple repositories:

import { createServer } from '@elaraai/e3-api-server';

const server = await createServer({
  reposDir: '/path/to/repos',  // Each subdirectory is a repo
  port: 3000,
  host: 'localhost',
});

await server.start();
// Repos accessible at /repos/repo1, /repos/repo2, etc.

With Authentication

import { createServer } from '@elaraai/e3-api-server';

const server = await createServer({
  singleRepoPath: '/path/to/repo',
  port: 3000,
  oidc: {
    baseUrl: 'http://localhost:3000',
    tokenExpiry: '1h',
    refreshTokenExpiry: '90d',
  },
});

await server.start();
// OIDC endpoints available at /.well-known/*, /oauth2/*, /device

ServerConfig Options

interface ServerConfig {
  // Repository mode (specify exactly one)
  singleRepoPath?: string;  // Single repo at /repos/default
  reposDir?: string;        // Multi-repo from subdirectories

  // Server options
  port?: number;            // Default: 3000
  host?: string;            // Default: 'localhost'
  cors?: boolean;           // Enable CORS (default: false)

  // Authentication (optional)
  auth?: AuthConfig;        // External JWT validation
  oidc?: OidcConfig;        // Built-in OIDC provider
}

API Endpoints

All endpoints are prefixed with /api/repos/:repo where :repo is:

• default in single-repo mode
• The repository name in multi-repo mode

Repository

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/repos | List available repositories (multi-repo mode) | | PUT | /api/repos/:repo | Create repository (multi-repo mode) | | DELETE | /api/repos/:repo | Delete repository (multi-repo mode, async) | | GET | /api/repos/:repo/status | Repository status (counts) | | POST | /api/repos/:repo/gc | Start garbage collection (async) | | GET | /api/repos/:repo/gc/:id | Get GC status |

Packages

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/repos/:repo/packages | List all packages | | GET | /api/repos/:repo/packages/:name/:version | Get package details | | POST | /api/repos/:repo/packages | Import package (zip body) | | GET | /api/repos/:repo/packages/:name/:version/export | Export package as zip | | DELETE | /api/repos/:repo/packages/:name/:version | Remove package |

Workspaces

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/repos/:repo/workspaces | List all workspaces | | POST | /api/repos/:repo/workspaces | Create workspace | | GET | /api/repos/:repo/workspaces/:ws | Get workspace info | | GET | /api/repos/:repo/workspaces/:ws/status | Get workspace status (datasets, tasks, summary) | | POST | /api/repos/:repo/workspaces/:ws/deploy | Deploy package to workspace | | DELETE | /api/repos/:repo/workspaces/:ws | Remove workspace | | GET | /api/repos/:repo/workspaces/:ws/export | Export workspace as package zip |

Datasets

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/repos/:repo/workspaces/:ws/datasets | List root datasets | | GET | /api/repos/:repo/workspaces/:ws/datasets/*path | Get dataset value (BEAST2) | | PUT | /api/repos/:repo/workspaces/:ws/datasets/*path | Set dataset value (BEAST2) |

Tasks

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/repos/:repo/workspaces/:ws/tasks | List tasks | | GET | /api/repos/:repo/workspaces/:ws/tasks/:task | Get task details |

Execution

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/repos/:repo/workspaces/:ws/dataflow/start | Start dataflow (async, returns immediately) | | POST | /api/repos/:repo/workspaces/:ws/dataflow/execute | Execute dataflow (blocking, returns result) | | GET | /api/repos/:repo/workspaces/:ws/dataflow/graph | Get dependency graph | | GET | /api/repos/:repo/workspaces/:ws/dataflow/logs/:task | Read task logs | | GET | /api/repos/:repo/workspaces/:ws/dataflow/state | Get current execution state |

Request/Response Format

All requests and responses use BEAST2 binary encoding with Content-Type: application/beast2.

Response bodies are wrapped in a variant type:

• { type: 'success', value: <result> } - Operation succeeded
• { type: 'error', value: <error> } - Operation failed

Error variants include:

• workspace_not_found - Workspace doesn't exist
• workspace_not_deployed - No package deployed to workspace
• workspace_locked - Workspace is locked by another process
• package_not_found - Package doesn't exist
• package_exists - Package already exists
• dataset_not_found - Dataset path doesn't exist
• task_not_found - Task doesn't exist
• internal - Internal server error

Using with e3-api-client

import { workspaceList, workspaceStatus, datasetGet } from '@elaraai/e3-api-client';

const baseUrl = 'http://localhost:3000';
const repo = 'default';  // In single-repo mode
const options = { token: '' };  // Empty token if no auth configured

// List workspaces
const workspaces = await workspaceList(baseUrl, repo, options);

// Get workspace status
const status = await workspaceStatus(baseUrl, repo, 'my-workspace', options);

// Get dataset value
const path = [{ value: 'inputs' }, { value: 'data' }];
const data = await datasetGet(baseUrl, repo, 'my-workspace', path, options);

Claude Code plugin

The East ecosystem also ships a Claude Code plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the elaraai marketplace:

# Inside Claude Code
/plugin marketplace add elaraai/east-workspace
/plugin install east@elaraai

# From a terminal
claude plugin marketplace add elaraai/east-workspace
claude plugin install east@elaraai

License

BSL 1.1. See LICENSE.md.

Ecosystem

• East: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.

  • @elaraai/east: Core language SDK with type system, expressions, and reference JS compiler

• East Node: Node.js platform functions for I/O, databases, and system operations.

  • @elaraai/east-node-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • @elaraai/east-node-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • @elaraai/east-node-cli: CLI for running East IR programs in Node.js

• East C: C11 native runtime for executing East IR. Distributed via npm (launcher + per-platform optional dependencies) and as tarballs on each GitHub Release.

  • @elaraai/east-c-cli: npm launcher — installs the matching native binary as an optional dependency
  • east-c: Core runtime — type system, IR interpreter, builtins, serialization (Beast2, JSON, CSV, East text)
  • east-c-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-c-cli: CLI for running East IR programs natively

• East Python: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.

  • east-py: Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
  • east-py-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-py-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • east-py-cli: CLI for running East IR programs in Python
  • east-py-datascience (PyPI) + @elaraai/east-py-datascience (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)

• East UI: Typed UI component definitions and React renderer, plus VS Code preview.

  • @elaraai/east-ui: 50+ typed UI components for layouts, forms, charts, tables, dialogs
  • @elaraai/east-ui-components: React renderer with Chakra UI v3 styling
  • @elaraai/e3-ui: e3 + UI bridge — Data bindings, e3.ui() task, manifest
  • @elaraai/e3-ui-components: React Query hooks and preview components for the e3 API
  • east-ui-preview: VS Code extension for live East UI component preview

• e3 — East Execution Engine: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.

  • @elaraai/e3: SDK for authoring e3 packages with typed tasks and pipelines
  • @elaraai/e3-core: Object store, dataflow orchestrator, execution state
  • @elaraai/e3-types: Shared type definitions for e3 packages
  • @elaraai/e3-cli: e3 repo, e3 package, e3 workspace, e3 start, e3 watch, e3 logs commands
  • @elaraai/e3-api-client: HTTP client for remote e3 repositories
  • @elaraai/e3-api-server: REST API server for e3 repositories
  • @elaraai/e3-api-tests: Shared API compliance test suites

Links

• East Language
• East Python Runtime
• Elara AI
• Issues
• [email protected]

About Elara

East is developed by Elara AI Pty Ltd, an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.

Developed by Elara AI Pty Ltd.

Developed by Elara AI Pty Ltd