@oasisomniverse/web8-api 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# @oasisomniverse/web8-api
+
+Isomorphic (Node 18+ and browser) JavaScript/TypeScript-friendly client for the
+**WEB8 OASIS Galactic Mesh API** - fractal holonic mesh node registration,
+link/route computation, self-healing message relay, and protocol-bridge
+translation between external wire formats and the unified `MeshMessage`
+envelope, built on the OASIS2 WEB8 WebAPI.
+
+Zero dependencies. Wraps the global `fetch`. Works the same in Node and the
+browser.
+
+## Installation
+
+```bash
+npm install @oasisomniverse/web8-api
+```
+
+## Quick start
+
+```js
+const { Web8Client } = require('@oasisomniverse/web8-api');
+// or: import { Web8Client } from '@oasisomniverse/web8-api';
+
+const web8 = new Web8Client({ baseUrl: 'https://api.web8.oasisomniverse.one' });
+
+const { isError, message, result } = await web8.mesh.registerNode({ name: 'edge-node-1' });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+## Calling any endpoint
+
+Every controller on the OASIS2 WEB8 WebAPI is reachable as a lowerCamel
+property on the client (`web8.mesh`, `web8.protocolBridge`). Every generated
+method takes a single args object:
+
+- Any key matching a `{token}` in the route template is consumed and
+  substituted into the URL (case-insensitive match).
+- Any remaining keys become the query string (GET/DELETE) or JSON body
+  (POST/PUT) - **matching the real `[FromQuery]`/`[FromBody]` binding of the
+  underlying C# action**, not just the HTTP verb. `endpoints.json` records
+  exactly which arg names are query-bound (and which single arg is the whole
+  body, for actions like `TranslateInbound` whose entire body is one
+  primitive `[FromBody] string`) per operation - see [`docs/`](./docs/README.md)
+  for the per-method breakdown.
+
+```js
+// POST v1/mesh/nodes/{nodeId}/heartbeat -> nodeId consumed as a route token
+await web8.mesh.heartbeat({ nodeId });
+
+// GET v1/mesh/route -> all args become query params
+const route = await web8.mesh.computeRoute({ sourceNodeId, destinationNodeId });
+
+// POST v1/mesh/links -> nodeAId/nodeBId/latencyMs are all [FromQuery] even
+// though this is a POST, so they're sent on the URL - no JSON body is sent
+await web8.mesh.addLink({ nodeAId, nodeBId, latencyMs: 12 });
+
+// POST v1/protocol-bridge/translate-inbound -> format/sourceNodeId/destinationNodeId
+// are [FromQuery]; rawPayload is the single [FromBody] string, so it becomes
+// the raw JSON body itself (not wrapped in an object)
+const inbound = await web8.protocolBridge.translateInbound({
+  format: 'Mqtt', sourceNodeId, destinationNodeId, rawPayload: '{"temp":21.5}'
+});
+```
+
+Every response has the shape:
+
+```ts
+interface OASISResponse<T = any> {
+  isError: boolean;
+  message: string | null;
+  result: T;
+  raw: any;
+  statusCode: number;
+}
+```
+
+## Auth
+
+WEB8 is an internal galactic-mesh/protocol-bridge layer that sits behind the
+same OASIS avatar identity as WEB4/WEB5/WEB6/WEB7 - it has no avatar/login
+endpoints of its own. Reuse a JWT you've already obtained elsewhere (e.g.
+from `web4-oasis-api`'s `client.auth.login()`):
+
+```js
+web8.setToken(jwtToken);
+```
+
+## Module examples
+
+### Mesh (`web8.mesh`)
+
+```js
+const nodeA = await web8.mesh.registerNode({ name: 'edge-node-a' });
+const nodeB = await web8.mesh.registerNode({ name: 'edge-node-b' });
+await web8.mesh.addLink({ nodeAId: nodeA.result.id, nodeBId: nodeB.result.id, latencyMs: 12 });
+await web8.mesh.heartbeat({ nodeId: nodeA.result.id });
+
+const route = await web8.mesh.computeRoute({ sourceNodeId: nodeA.result.id, destinationNodeId: nodeB.result.id });
+const relay = await web8.mesh.sendMessage({ sourceNodeId: nodeA.result.id, destinationNodeId: nodeB.result.id, payload: 'hello' });
+```
+
+### Protocol Bridge (`web8.protocolBridge`)
+
+```js
+const inbound = await web8.protocolBridge.translateInbound({
+  format: 'Mqtt',
+  sourceNodeId,
+  destinationNodeId,
+  rawPayload: '{"temp":21.5}'
+});
+
+// targetFormat is [FromQuery]; the rest of the args become the MeshMessage
+// JSON body directly (not nested under a "message" key)
+const outbound = await web8.protocolBridge.translateOutbound({ targetFormat: 'Json', ...inbound.result });
+```
+
+## Module reference
+
+2 modules, 8 operations in total. Full per-method tables live in
+[`docs/`](./docs/README.md).
+
+| Client property | Route prefix | Operations |
+| --- | --- | --- |
+| `web8.mesh` | `v1/mesh` | 6 |
+| `web8.protocolBridge` | `v1/protocol-bridge` | 2 |
+
+See [`docs/README.md`](./docs/README.md) for the full generated reference,
+or [`docs/modules/`](./docs/modules) for per-module method tables with
+parameter and route details.
+
+## Regenerating
+
+The generated modules, type declarations and docs are produced from
+`endpoints.json` (extracted from the WEB8 WebAPI controller source):
+
+```bash
+npm run generate   # src/modules/*.js + src/modules/index.js
+npm run types      # src/modules/*.d.ts + index.d.ts + src/core/types.d.ts
+npm run docs       # docs/README.md + docs/modules/*.md
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/docs/README.md

@@ -0,0 +1,20 @@
+# WEB8 Galactic Mesh & Protocol Bridge API — JavaScript SDK Reference
+
+Generated from `endpoints.json` (extracted from the WebAPI controllers) by
+`scripts/generate-full-docs.js`. Regenerate the full pipeline after the API
+changes:
+
+```
+node scripts/extract-endpoints.js
+node scripts/generate-modules.js
+node scripts/generate-full-docs.js
+```
+
+- [Module Reference](#module-reference) (2 modules, 8 operations)
+
+## Module Reference
+
+| Client property | Route prefix | Operations |
+| --- | --- | --- |
+| [`web8.mesh`](modules/Mesh.md) | `v1/mesh` | 6 |
+| [`web8.protocolBridge`](modules/ProtocolBridge.md) | `v1/protocol-bridge` | 2 |

package/docs/modules/Mesh.md

@@ -0,0 +1,312 @@
+# Mesh — `web8.mesh`
+
+Source controller: [`MeshController.cs`](https://github.com/NextGenSoftwareUK/OASIS2/blob/main/WEB8/NextGenSoftware.OASIS.Web8.WebAPI/Controllers/MeshController.cs)
+Route prefix: `v1/mesh`
+6 operation(s).
+
+Every method takes a single args object: any key matching a `{token}` in the route is substituted into the URL; everything else becomes the query string (GET/DELETE) or JSON body (POST/PUT). Every call resolves to the standard OASIS envelope:
+
+```ts
+{
+  isError: boolean;
+  isWarning: boolean;
+  message: string;
+  errorCode?: string;
+  result: T; // see each endpoint's Response section below
+}
+```
+
+## Operations
+
+### `addLink`
+
+**POST** `v1/mesh/links`
+
+**Request**
+
+Body fields:
+
+| Field | Type |
+| --- | --- |
+| `nodeAId` | `Guid` |
+| `nodeBId` | `Guid` |
+| `latencyMs` | `double (optional)` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.addLink({
+    nodeAId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    nodeBId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    latencyMs: 1.0
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `computeRoute`
+
+**GET** `v1/mesh/route`
+
+**Request**
+
+Query parameters:
+
+| Field | Type |
+| --- | --- |
+| `sourceNodeId` | `Guid` |
+| `destinationNodeId` | `Guid` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `Guid` (array)
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.computeRoute({
+    sourceNodeId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    destinationNodeId: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
+}
+```
+
+---
+
+### `getNodes`
+
+**GET** `v1/mesh/nodes`
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `GalacticNode` (array)
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `Name` | `string` |
+| `Type` | `NodeType` |
+| `EndpointUrl` | `string` |
+| `IsSovereign` | `bool` |
+| `RegisteredUtc` | `DateTime` |
+| `LastSeenUtc` | `DateTime` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.getNodes({});
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": [{ "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "example string", "Type": {  }, "EndpointUrl": "example string", "IsSovereign": true, "RegisteredUtc": "2026-01-01T00:00:00Z", "LastSeenUtc": "2026-01-01T00:00:00Z" }]
+}
+```
+
+---
+
+### `heartbeat`
+
+**POST** `v1/mesh/nodes/{nodeId}/heartbeat`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `nodeId` | `Guid` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.heartbeat({
+    nodeId: '<nodeId>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `registerNode`
+
+The WEB8 fractal holonic mesh - register nodes, declare links, compute routes and relay messages with self-healing failover.
+
+**POST** `v1/mesh/nodes`
+
+**Request**
+
+Body type: `GalacticNode`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `Name` | `string` |
+| `Type` | `NodeType` |
+| `EndpointUrl` | `string` |
+| `IsSovereign` | `bool` |
+| `RegisteredUtc` | `DateTime` |
+| `LastSeenUtc` | `DateTime` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `GalacticNode`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `Name` | `string` |
+| `Type` | `NodeType` |
+| `EndpointUrl` | `string` |
+| `IsSovereign` | `bool` |
+| `RegisteredUtc` | `DateTime` |
+| `LastSeenUtc` | `DateTime` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.registerNode({
+    id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    name: "example string",
+    type: {  },
+    endpointUrl: "example string",
+    isSovereign: true,
+    registeredUtc: "2026-01-01T00:00:00Z",
+    lastSeenUtc: "2026-01-01T00:00:00Z"
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "example string", "Type": {  }, "EndpointUrl": "example string", "IsSovereign": true, "RegisteredUtc": "2026-01-01T00:00:00Z", "LastSeenUtc": "2026-01-01T00:00:00Z" }
+}
+```
+
+---
+
+### `sendMessage`
+
+Routes and relays a message hop-by-hop to its destination, self-healing around any failed/stale node.
+
+**POST** `v1/mesh/send`
+
+**Request**
+
+Body type: `MeshMessage`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `SourceNodeId` | `Guid` |
+| `DestinationNodeId` | `Guid` |
+| `Payload` | `string` |
+| `Ttl` | `int` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `MeshRouteResult`
+
+| Field | Type |
+| --- | --- |
+| `MessageId` | `Guid` |
+| `Path` | `List<Guid>` |
+| `TotalLatencyMs` | `double` |
+| `Delivered` | `bool` |
+| `RelayLog` | `List<string>` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.mesh.sendMessage({
+    id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    sourceNodeId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    destinationNodeId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    payload: "example string",
+    ttl: 1
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "MessageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Path": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"], "TotalLatencyMs": 1.0, "Delivered": true, "RelayLog": ["example string"] }
+}
+```
+

package/docs/modules/ProtocolBridge.md

@@ -0,0 +1,123 @@
+# ProtocolBridge — `web8.protocolBridge`
+
+Source controller: [`ProtocolBridgeController.cs`](https://github.com/NextGenSoftwareUK/OASIS2/blob/main/WEB8/NextGenSoftware.OASIS.Web8.WebAPI/Controllers/ProtocolBridgeController.cs)
+Route prefix: `v1/protocol-bridge`
+2 operation(s).
+
+Every method takes a single args object: any key matching a `{token}` in the route is substituted into the URL; everything else becomes the query string (GET/DELETE) or JSON body (POST/PUT). Every call resolves to the standard OASIS envelope:
+
+```ts
+{
+  isError: boolean;
+  isWarning: boolean;
+  message: string;
+  errorCode?: string;
+  result: T; // see each endpoint's Response section below
+}
+```
+
+## Operations
+
+### `translateInbound`
+
+Translates any external system's wire format into the unified WEB8 MeshMessage envelope and back.
+
+**POST** `v1/protocol-bridge/translate-inbound`
+
+**Request**
+
+Body fields:
+
+| Field | Type |
+| --- | --- |
+| `format` | `BridgeFormat` |
+| `sourceNodeId` | `Guid` |
+| `destinationNodeId` | `Guid` |
+| `rawPayload` | `string` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `MeshMessage`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `SourceNodeId` | `Guid` |
+| `DestinationNodeId` | `Guid` |
+| `Payload` | `string` |
+| `Ttl` | `int` |
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.protocolBridge.translateInbound({
+    format: '<format>',
+    sourceNodeId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    destinationNodeId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    rawPayload: 'example string'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "SourceNodeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "DestinationNodeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Payload": "example string", "Ttl": 1 }
+}
+```
+
+---
+
+### `translateOutbound`
+
+**POST** `v1/protocol-bridge/translate-outbound`
+
+**Request**
+
+Body type: `MeshMessage`
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `SourceNodeId` | `Guid` |
+| `DestinationNodeId` | `Guid` |
+| `Payload` | `string` |
+| `Ttl` | `int` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `string`
+
+**Example**
+
+```js
+const { isError, message, result } = await web8.protocolBridge.translateOutbound({
+    targetFormat: '<targetFormat>',
+    id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    sourceNodeId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    destinationNodeId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    payload: "example string",
+    ttl: 1
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": "example string"
+}
+```
+

package/index.d.ts

@@ -0,0 +1,44 @@
+// AUTO-GENERATED by scripts/generate-types.js - do not hand-edit.
+import type { OASISResponse, OASISSession } from './src/core/types';
+import type { MeshModule } from './src/modules/Mesh';
+import type { ProtocolBridgeModule } from './src/modules/ProtocolBridge';
+
+export type { OASISResponse, OASISSession };
+
+export interface Web8ClientOptions {
+  baseUrl?: string;
+  persistSession?: boolean;
+  fetchImpl?: typeof fetch;
+}
+
+export declare class HttpClient {
+  constructor(options?: { baseUrl?: string; tokenStore?: unknown; fetchImpl?: typeof fetch });
+  setBaseUrl(baseUrl: string): void;
+  request(verb: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, options?: Record<string, any>): Promise<OASISResponse>;
+  get(path: string, options?: Record<string, any>): Promise<OASISResponse>;
+  post(path: string, options?: Record<string, any>): Promise<OASISResponse>;
+  put(path: string, options?: Record<string, any>): Promise<OASISResponse>;
+  delete(path: string, options?: Record<string, any>): Promise<OASISResponse>;
+}
+
+export declare class TokenStore {
+  constructor(options?: { persist?: boolean });
+  getSession(): OASISSession | null;
+  getToken(): string | null;
+  setSession(session: OASISSession | null): void;
+  clear(): void;
+}
+
+export declare const DEFAULT_BASE_URL: string;
+
+export declare class Web8Client {
+  constructor(options?: Web8ClientOptions);
+  readonly http: HttpClient;
+  readonly tokenStore: TokenStore;
+  readonly mesh: MeshModule;
+  readonly protocolBridge: ProtocolBridgeModule;
+  setBaseUrl(baseUrl: string): void;
+  setToken(jwtToken: string, sessionExtras?: Partial<OASISSession>): void;
+}
+
+export default Web8Client;

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./src/index');

package/index.mjs

@@ -0,0 +1,4 @@
+import cjs from './index.js';
+
+export const { Web8Client, HttpClient, TokenStore, DEFAULT_BASE_URL } = cjs;
+export default Web8Client;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@oasisomniverse/web8-api",
+  "version": "1.0.0",
+  "publishConfig": { "access": "public" },
+  "description": "Isomorphic (Node + browser) JavaScript/TypeScript-friendly client for the WEB8 OASIS Galactic Mesh API - fractal holonic mesh node registration, link/route computation, self-healing message relay, and protocol-bridge translation between external wire formats and the unified MeshMessage envelope, built on the OASIS2 WEB8 WebAPI.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "src",
+    "docs"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate-modules.js",
+    "docs": "node scripts/generate-docs.js",
+    "types": "node scripts/generate-types.js",
+    "test": "node --test test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NextGenSoftwareUK/OASIS-API-Javascript-Package-WEB8.git"
+  },
+  "author": "NextGen Software Ltd",
+  "license": "MIT",
+  "keywords": [
+    "WEB8 Galactic Mesh API",
+    "WEB8 WebAPI",
+    "OASIS Galactic Mesh",
+    "Holonic Mesh",
+    "Self-Healing Routing",
+    "Protocol Bridge",
+    "Mesh Networking",
+    "OASIS API",
+    "WEB 4",
+    "WEB 5",
+    "WEB 6",
+    "WEB 7",
+    "WEB 8",
+    "Blockchain",
+    "Interoperable",
+    "Metaverse",
+    "Aggregation",
+    "HOT-Swappable-Architecture",
+    "Decentralised",
+    "Distributed",
+    "Abstraction-Layer",
+    "Multi-Network",
+    "SSO",
+    "Agent-Centric",
+    "GOD-Protocol/API",
+    "More Coming..."
+  ]
+}

package/src/core/httpClient.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const DEFAULT_BASE_URL = 'https://api.web8.oasisomniverse.one';
+
+function buildQueryString(query) {
+  const entries = Object.entries(query || {}).filter(([, v]) => v !== undefined && v !== null);
+  if (!entries.length) return '';
+  const params = new URLSearchParams();
+  for (const [key, value] of entries) {
+    params.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+  return `?${params.toString()}`;
+}
+
+/**
+ * Thin isomorphic HTTP client around the global fetch API (Node 18+, all modern browsers).
+ * Every WEB8 Galactic Mesh & Protocol Bridge API call ultimately goes through `request()` below - there are no mocked
+ * or stubbed responses anywhere in this SDK.
+ */
+class HttpClient {
+  constructor({ baseUrl = DEFAULT_BASE_URL, tokenStore, fetchImpl = globalThis.fetch } = {}) {
+    if (!fetchImpl) {
+      throw new Error(
+        'No global fetch implementation found. Use Node 18+, a modern browser, or pass { fetchImpl } explicitly.'
+      );
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.tokenStore = tokenStore;
+    this.fetchImpl = fetchImpl;
+  }
+
+  setBaseUrl(baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+  }
+
+  /**
+   * @param {string} verb GET | POST | PUT | DELETE
+   * @param {string} path e.g. "v1/complete"
+   * @param {object} [options]
+   * @param {object} [options.query] query string params (GET/DELETE)
+   * @param {object} [options.body] JSON body (POST/PUT/DELETE)
+   * @param {boolean} [options.auth] attach Authorization: Bearer <token> (default true)
+   * @param {string} [options.token] override token for this single request
+   */
+  async request(verb, path, { query, body, auth = true, token } = {}) {
+    const url = `${this.baseUrl}/${path.replace(/^\/+/, '')}${buildQueryString(query)}`;
+    const headers = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json'
+    };
+
+    const bearer = token || (auth ? this.tokenStore?.getToken() : null);
+    if (bearer) headers.Authorization = `Bearer ${bearer}`;
+
+    const init = { method: verb, headers };
+    if (body !== undefined && verb !== 'GET') init.body = JSON.stringify(body);
+
+    let res;
+    try {
+      res = await this.fetchImpl(url, init);
+    } catch (err) {
+      return { isError: true, message: `Network error calling ${url}: ${err.message}`, exception: err };
+    }
+
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+
+    if (!res.ok) {
+      const message =
+        json?.result?.message || json?.message || json?.title || `Request failed with status ${res.status}`;
+      return { isError: true, message, statusCode: res.status, raw: json };
+    }
+
+    // OASIS responses are typically { isError, message, result: { isError, message, result: <payload> } }.
+    // We surface the innermost payload as `.result` while keeping the full envelope available as `.raw`.
+    const inner = json?.result !== undefined ? json.result : json;
+    const payload = inner?.result !== undefined ? inner.result : inner;
+
+    return {
+      isError: Boolean(inner?.isError || json?.isError),
+      message: inner?.message || json?.message || null,
+      result: payload,
+      raw: json,
+      statusCode: res.status
+    };
+  }
+
+  get(path, options) {
+    return this.request('GET', path, options);
+  }
+
+  post(path, options) {
+    return this.request('POST', path, options);
+  }
+
+  put(path, options) {
+    return this.request('PUT', path, options);
+  }
+
+  delete(path, options) {
+    return this.request('DELETE', path, options);
+  }
+}
+
+module.exports = { HttpClient, DEFAULT_BASE_URL };

package/src/core/routeHelper.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const TOKEN_PATTERN = /\{(\w+)(?::\w+)?\}/g;
+
+/**
+ * Resolves a route template like "get-by-id/{id}" against an args object,
+ * substituting path tokens and returning the resolved path plus whatever
+ * args were *not* consumed as path tokens (these become the query/body).
+ */
+function resolveRoute(routeTemplate, args = {}) {
+  const consumed = new Set();
+  const path = routeTemplate.replace(TOKEN_PATTERN, (match, name) => {
+    const key = Object.keys(args).find((k) => k.toLowerCase() === name.toLowerCase());
+    consumed.add(key);
+    const value = key !== undefined ? args[key] : undefined;
+    if (value === undefined) {
+      throw new Error(`Missing required route parameter "${name}" for route "${routeTemplate}"`);
+    }
+    return encodeURIComponent(value);
+  });
+
+  const rest = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key)) rest[key] = value;
+  }
+
+  return { path, rest };
+}
+
+function takeKey(obj, name) {
+  const matchKey = Object.keys(obj).find((k) => k.toLowerCase() === name.toLowerCase());
+  if (matchKey === undefined) return { found: false, value: undefined };
+  const value = obj[matchKey];
+  delete obj[matchKey];
+  return { found: true, value };
+}
+
+/**
+ * Builds a bound method for a single WEB8 endpoint operation.
+ * @param {import('./httpClient').HttpClient} http
+ * @param {string} routePrefix e.g. "api/avatar"
+ * @param {string} verb GET | POST | PUT | DELETE
+ * @param {string} route route template relative to routePrefix, e.g. "get-by-id/{id}"
+ * @param {object} [opts]
+ * @param {string[]} [opts.query] arg names that ASP.NET binds from the query
+ *   string on this action regardless of HTTP verb (e.g. `[FromQuery]` flags
+ *   mixed into an otherwise-body-bound POST/PUT action). Always sent as query.
+ * @param {string} [opts.bodyParam] when the action's entire request body is a
+ *   single `[FromBody]` parameter (primitive or object), the JSON body is
+ *   that arg's value directly rather than the leftover-args object wrapped
+ *   around it.
+ */
+function makeOperation(http, routePrefix, verb, route, opts = {}) {
+  const declaredQueryKeys = opts.query || [];
+  const bodyParam = opts.bodyParam;
+
+  return async function operation(args = {}) {
+    const { path, rest } = resolveRoute(route, args);
+    const fullPath = path ? `${routePrefix}/${path}` : routePrefix;
+
+    const query = {};
+    for (const key of declaredQueryKeys) {
+      const { found, value } = takeKey(rest, key);
+      if (found) query[key] = value;
+    }
+
+    let body;
+    if (bodyParam) {
+      const { found, value } = takeKey(rest, bodyParam);
+      if (found) body = value;
+      // Any args left over that we don't recognize still get sent (as query)
+      // rather than silently dropped.
+      Object.assign(query, rest);
+    } else if (verb === 'GET' || verb === 'DELETE') {
+      Object.assign(query, rest);
+    } else {
+      body = Object.keys(rest).length ? rest : undefined;
+    }
+
+    const hasQuery = Object.keys(query).length > 0;
+    return http.request(verb, fullPath, { query: hasQuery ? query : undefined, body });
+  };
+}
+
+module.exports = { resolveRoute, makeOperation };

package/src/core/tokenStore.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const hasLocalStorage = typeof globalThis.localStorage !== 'undefined';
+const STORAGE_KEY = 'oasis_session';
+
+/**
+ * Holds the current JWT/avatar session for the SDK.
+ * In the browser it persists to localStorage by default; in Node (or when
+ * persistence is disabled) it simply lives in memory for the lifetime of
+ * the client instance. Callers can always set/get/clear explicitly.
+ */
+class TokenStore {
+  constructor({ persist = hasLocalStorage } = {}) {
+    this.persist = persist;
+    this._session = null;
+
+    if (this.persist) {
+      try {
+        const raw = globalThis.localStorage.getItem(STORAGE_KEY);
+        if (raw) this._session = JSON.parse(raw);
+      } catch {
+        this._session = null;
+      }
+    }
+  }
+
+  getSession() {
+    return this._session;
+  }
+
+  getToken() {
+    return this._session?.jwtToken || this._session?.token || null;
+  }
+
+  setSession(session) {
+    this._session = session || null;
+    if (this.persist) {
+      try {
+        if (session) globalThis.localStorage.setItem(STORAGE_KEY, JSON.stringify(session));
+        else globalThis.localStorage.removeItem(STORAGE_KEY);
+      } catch {
+        // Storage unavailable (e.g. private browsing) - in-memory session still works.
+      }
+    }
+  }
+
+  clear() {
+    this.setSession(null);
+  }
+}
+
+module.exports = { TokenStore };

package/src/core/types.d.ts

@@ -0,0 +1,18 @@
+// AUTO-GENERATED by scripts/generate-types.js - do not hand-edit.
+export interface OASISResponse<T = any> {
+  isError: boolean;
+  message: string | null;
+  result: T;
+  raw: any;
+  statusCode: number;
+}
+
+export interface OASISSession {
+  avatarId: string;
+  username: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  jwtToken: string;
+  refreshToken?: string;
+}

package/src/index.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { HttpClient, DEFAULT_BASE_URL } = require('./core/httpClient');
+const { TokenStore } = require('./core/tokenStore');
+const { attachGeneratedModules } = require('./modules/index');
+
+/**
+ * Main SDK entry point. Works in Node 18+ and any modern browser.
+ *
+ *   const { Web8Client } = require('@oasisomniverse/web8-api');
+ *   const web8 = new Web8Client({ baseUrl: 'https://api.web8.oasisomniverse.one' });
+ *   web8.setToken(jwtToken); // reuse a WEB4 OASIS JWT - WEB8 has no auth of its own
+ *   const node = await web8.mesh.registerNode({ name: 'edge-node-1' });
+ *
+ * Every controller on the WEB8 Mesh WebAPI is reachable as a lowerCamel
+ * property (web8.mesh, web8.protocolBridge). Generated methods take a single
+ * args object; route template tokens (e.g. {nodeId}) are consumed from it
+ * automatically, remaining keys become the query string (GET/DELETE) or JSON
+ * body (POST/PUT).
+ */
+class Web8Client {
+  constructor({ baseUrl = DEFAULT_BASE_URL, persistSession, fetchImpl } = {}) {
+    this.tokenStore = new TokenStore({ persist: persistSession });
+    this.http = new HttpClient({ baseUrl, tokenStore: this.tokenStore, fetchImpl });
+
+    attachGeneratedModules(this, this.http);
+  }
+
+  setBaseUrl(baseUrl) {
+    this.http.setBaseUrl(baseUrl);
+  }
+
+  /**
+   * WEB8 is an internal galactic-mesh/protocol-bridge layer sitting behind
+   * the same OASIS identity as WEB4/WEB5/WEB6/WEB7 - it has no avatar/auth
+   * endpoints of its own. Reuse a JWT you already obtained from the WEB4
+   * OASIS API (or your own backend) here.
+   */
+  setToken(jwtToken, sessionExtras = {}) {
+    this.tokenStore.setSession({ ...sessionExtras, jwtToken });
+  }
+}
+
+module.exports = { Web8Client, HttpClient, TokenStore, DEFAULT_BASE_URL };
+module.exports.default = Web8Client;

package/src/modules/Mesh.d.ts

@@ -0,0 +1,24 @@
+// AUTO-GENERATED by scripts/generate-types.js - do not hand-edit.
+import type { OASISResponse } from '../core/types';
+
+export declare class MeshModule {
+  constructor(http: unknown);
+
+  /** POST v1/mesh/links (query: nodeAId, nodeBId, latencyMs) */
+  addLink(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** GET v1/mesh/route (query: sourceNodeId, destinationNodeId) */
+  computeRoute(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** GET v1/mesh/nodes */
+  getNodes(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** POST v1/mesh/nodes/{nodeId}/heartbeat */
+  heartbeat(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** POST v1/mesh/nodes */
+  registerNode(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** POST v1/mesh/send */
+  sendMessage(args?: Record<string, any>): Promise<OASISResponse>;
+}

package/src/modules/Mesh.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// AUTO-GENERATED by scripts/generate-modules.js from endpoints.json - do not hand-edit.
+// Regenerate with: node scripts/generate-modules.js
+
+const { makeOperation } = require('../core/routeHelper');
+
+/**
+ * Generated wrapper for v1/mesh (source: WEB8 Mesh WebAPI MeshController.cs).
+ * Every method takes a single args object: path-template tokens (e.g. {id})
+ * are consumed from it automatically; any remaining keys are sent as the
+ * query string (GET/DELETE) or JSON body (POST/PUT).
+ */
+class MeshModule {
+  constructor(http) {
+    this._http = http;
+
+    // POST v1/mesh/links (query: nodeAId, nodeBId, latencyMs)
+    this.addLink = makeOperation(http, "v1/mesh", "POST", "links", {"query":["nodeAId","nodeBId","latencyMs"]});
+    // GET v1/mesh/route (query: sourceNodeId, destinationNodeId)
+    this.computeRoute = makeOperation(http, "v1/mesh", "GET", "route", {"query":["sourceNodeId","destinationNodeId"]});
+    // GET v1/mesh/nodes
+    this.getNodes = makeOperation(http, "v1/mesh", "GET", "nodes");
+    // POST v1/mesh/nodes/{nodeId}/heartbeat
+    this.heartbeat = makeOperation(http, "v1/mesh", "POST", "nodes/{nodeId}/heartbeat");
+    // POST v1/mesh/nodes
+    this.registerNode = makeOperation(http, "v1/mesh", "POST", "nodes");
+    // POST v1/mesh/send
+    this.sendMessage = makeOperation(http, "v1/mesh", "POST", "send");
+  }
+}
+
+module.exports = { MeshModule };

package/src/modules/ProtocolBridge.d.ts

@@ -0,0 +1,12 @@
+// AUTO-GENERATED by scripts/generate-types.js - do not hand-edit.
+import type { OASISResponse } from '../core/types';
+
+export declare class ProtocolBridgeModule {
+  constructor(http: unknown);
+
+  /** POST v1/protocol-bridge/translate-inbound (query: format, sourceNodeId, destinationNodeId) (body: rawPayload) */
+  translateInbound(args?: Record<string, any>): Promise<OASISResponse>;
+
+  /** POST v1/protocol-bridge/translate-outbound (query: targetFormat) */
+  translateOutbound(args?: Record<string, any>): Promise<OASISResponse>;
+}

package/src/modules/ProtocolBridge.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// AUTO-GENERATED by scripts/generate-modules.js from endpoints.json - do not hand-edit.
+// Regenerate with: node scripts/generate-modules.js
+
+const { makeOperation } = require('../core/routeHelper');
+
+/**
+ * Generated wrapper for v1/protocol-bridge (source: WEB8 Mesh WebAPI ProtocolBridgeController.cs).
+ * Every method takes a single args object: path-template tokens (e.g. {id})
+ * are consumed from it automatically; any remaining keys are sent as the
+ * query string (GET/DELETE) or JSON body (POST/PUT).
+ */
+class ProtocolBridgeModule {
+  constructor(http) {
+    this._http = http;
+
+    // POST v1/protocol-bridge/translate-inbound (query: format, sourceNodeId, destinationNodeId) (body: rawPayload)
+    this.translateInbound = makeOperation(http, "v1/protocol-bridge", "POST", "translate-inbound", {"query":["format","sourceNodeId","destinationNodeId"],"bodyParam":"rawPayload"});
+    // POST v1/protocol-bridge/translate-outbound (query: targetFormat)
+    this.translateOutbound = makeOperation(http, "v1/protocol-bridge", "POST", "translate-outbound", {"query":["targetFormat"]});
+  }
+}
+
+module.exports = { ProtocolBridgeModule };

package/src/modules/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// AUTO-GENERATED by scripts/generate-modules.js - do not hand-edit.
+const { MeshModule } = require('./Mesh');
+const { ProtocolBridgeModule } = require('./ProtocolBridge');
+
+/**
+ * Attaches every generated module to the client under its lowerCamel controller
+ * name (e.g. client.completion, client.images, client.holonicMemory).
+ */
+function attachGeneratedModules(client, http) {
+  client.mesh = client.mesh || new MeshModule(http);
+  client.protocolBridge = client.protocolBridge || new ProtocolBridgeModule(http);
+  return client;
+}
+
+module.exports = { attachGeneratedModules };