@oasisomniverse/web4-api 2.0.0

package/index.d.ts

@@ -0,0 +1,106 @@
+// AUTO-GENERATED by scripts/generate-types.js - do not hand-edit.
+import type { OASISResponse, OASISSession } from './src/core/types';
+import type { AuthModule } from './src/modules/Auth';
+import type { AvatarModule } from './src/modules/Avatar';
+import type { BridgeModule } from './src/modules/Bridge';
+import type { ChatModule } from './src/modules/Chat';
+import type { ClanModule } from './src/modules/Clan';
+import type { CompetitionModule } from './src/modules/Competition';
+import type { DataModule } from './src/modules/Data';
+import type { EOSIOModule } from './src/modules/EOSIO';
+import type { EggsModule } from './src/modules/Eggs';
+import type { FilesModule } from './src/modules/Files';
+import type { GiftsModule } from './src/modules/Gifts';
+import type { HealthModule } from './src/modules/Health';
+import type { HolochainModule } from './src/modules/Holochain';
+import type { HyperDriveModule } from './src/modules/HyperDrive';
+import type { KarmaModule } from './src/modules/Karma';
+import type { KeysModule } from './src/modules/Keys';
+import type { MapModule } from './src/modules/Map';
+import type { MessagingModule } from './src/modules/Messaging';
+import type { NftModule } from './src/modules/Nft';
+import type { OLandModule } from './src/modules/OLand';
+import type { ONETModule } from './src/modules/ONET';
+import type { ONODEModule } from './src/modules/ONODE';
+import type { ProviderModule } from './src/modules/Provider';
+import type { SearchModule } from './src/modules/Search';
+import type { SeedsModule } from './src/modules/Seeds';
+import type { SettingsModule } from './src/modules/Settings';
+import type { ShareModule } from './src/modules/Share';
+import type { SocialModule } from './src/modules/Social';
+import type { SolanaModule } from './src/modules/Solana';
+import type { StatsModule } from './src/modules/Stats';
+import type { SubscriptionModule } from './src/modules/Subscription';
+import type { VideoModule } from './src/modules/Video';
+import type { WalletModule } from './src/modules/Wallet';
+
+export type { OASISResponse, OASISSession };
+
+export interface OASISClientOptions {
+  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 OASISClient {
+  constructor(options?: OASISClientOptions);
+  readonly http: HttpClient;
+  readonly tokenStore: TokenStore;
+  readonly auth: AuthModule;
+  readonly avatar: AvatarModule;
+  readonly bridge: BridgeModule;
+  readonly chat: ChatModule;
+  readonly clan: ClanModule;
+  readonly competition: CompetitionModule;
+  readonly data: DataModule;
+  readonly eOSIO: EOSIOModule;
+  readonly eggs: EggsModule;
+  readonly files: FilesModule;
+  readonly gifts: GiftsModule;
+  readonly health: HealthModule;
+  readonly holochain: HolochainModule;
+  readonly hyperDrive: HyperDriveModule;
+  readonly karma: KarmaModule;
+  readonly keys: KeysModule;
+  readonly map: MapModule;
+  readonly messaging: MessagingModule;
+  readonly nft: NftModule;
+  readonly oLand: OLandModule;
+  readonly oNET: ONETModule;
+  readonly oNODE: ONODEModule;
+  readonly provider: ProviderModule;
+  readonly search: SearchModule;
+  readonly seeds: SeedsModule;
+  readonly settings: SettingsModule;
+  readonly share: ShareModule;
+  readonly social: SocialModule;
+  readonly solana: SolanaModule;
+  readonly stats: StatsModule;
+  readonly subscription: SubscriptionModule;
+  readonly video: VideoModule;
+  readonly wallet: WalletModule;
+  setBaseUrl(baseUrl: string): void;
+  setToken(jwtToken: string, sessionExtras?: Partial<OASISSession>): void;
+}
+
+export default OASISClient;

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 { OASISClient, HttpClient, TokenStore, DEFAULT_BASE_URL } = cjs;
+export default OASISClient;

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@oasisomniverse/web4-api",
+  "version": "2.0.0",
+  "publishConfig": { "access": "public" },
+  "description": "Isomorphic (Node + browser) JavaScript/TypeScript-friendly client for the WEB4 OASIS API - full coverage of the OASIS2 ONODE WebAPI (Avatar, Data, Karma, NFT, Wallet, Map, Search, HyperDrive, and more).",
+  "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-Javascipt-Package.git"
+  },
+  "homepage": "https://github.com/NextGenSoftwareUK/Our-World-OASIS-API-HoloNET-HoloUnity-And-.NET-HDK#readme",
+  "author": "NextGen Software Ltd",
+  "license": "MIT",
+  "keywords": [
+    "OASIS API",
+    "Avatar API",
+    "Karma API",
+    "Data API",
+    "SEEDS API",
+    "Keys/Wallets API",
+    "Providers API",
+    "WEB 3",
+    "WEB 4",
+    "WEB 5",
+    "Blockchain",
+    "NFT",
+    "Tokens",
+    "Crypto",
+    "Interoperable",
+    "Future-Prove",
+    "Metaverse",
+    "Aggregation",
+    "HOT-Swappable-Architecture",
+    "P2P",
+    "Decentralised",
+    "Distributed",
+    "Interoprability",
+    "Abstraction-Layer",
+    "Multi-Network",
+    "Multi-Chain",
+    "Bridging",
+    "Network-Of-Networks",
+    "SSO",
+    "Auto-FailOver",
+    "Auto-LoadBalancing",
+    "Auto-Replication", 
+    "Auto-Sync",
+    "Offline-Support",
+    "Write-Once-Deploy-Everywhere",
+    "Triple-Level-Quantum-Resistant-Encryption",
+    "Quantum",
+    "Encryption",
+    "Smart-Contracts",
+    "Intelligent-Key-Management",
+    "Zero-Lag",
+    "Zero-Downtime",
+    "Agent-Centric",
+    "Smart-City-Ready",
+    "WEB/2D/3D/AR/VR/IR/Map/Meta-Visusalization",
+    "Bio-feedback-Ready",
+    "IR-(Infinite-Reality)-Ready",
+    "Infinite-Players-Online-At-Same-Time",
+    "LAN/Bluetooth-Support",
+    "AI/Machine-Learning-Over-All-Of-World's-Aggregated-Data",
+    "HTTP-REST/gRPC/GraphQL/CLI/Native-Endpoints",
+    "Best-Of-All-Worlds",
+    "GOD-Protocol/API",
+    "Our-World-Geo-Location/AR/IR/Map-UI-(Game-of-Games-Engine)",
+    "One-World-Open-World-MMO-(VR)-UI-(Game-of-Games-Engine)",
+    "SEEDS", 
+    "Telos",
+    "TRON",
+    "Holochain",
+    "IPFS",
+    "Solana",
+    "EOS",
+    "Ethereum",
+    "MongoDB",
+    "Neo4j",
+    "SQLLite",
+    "ThreeFold",
+    "SOLID",
+    "ActivityPub",
+    "AzureCosmosDB",
+    "BlockStack",
+    "Chainlink",
+    "COSMOS",
+    "Elrond",
+    "Hashgraph",
+    "OrionProtocol",
+    "PLAN",
+    "Scuttlebutt",
+    "More Coming..."
+  ]
+}

package/src/core/httpClient.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const DEFAULT_BASE_URL = 'https://api.oasisweb4.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 OASIS 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. "api/avatar/authenticate"
+   * @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,50 @@
+'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 };
+}
+
+/**
+ * Builds a bound method for a single OASIS 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}"
+ */
+function makeOperation(http, routePrefix, verb, route) {
+  return async function operation(args = {}) {
+    const { path, rest } = resolveRoute(route, args);
+    const fullPath = path ? `${routePrefix}/${path}` : routePrefix;
+    const hasBody = Object.keys(rest).length > 0;
+
+    if (verb === 'GET') {
+      return http.get(fullPath, { query: hasBody ? rest : undefined });
+    }
+    return http.request(verb, fullPath, { body: hasBody ? rest : undefined });
+  };
+}
+
+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,46 @@
+'use strict';
+
+const { HttpClient, DEFAULT_BASE_URL } = require('./core/httpClient');
+const { TokenStore } = require('./core/tokenStore');
+const { attachGeneratedModules } = require('./modules/index');
+const { AuthModule } = require('./modules/Auth');
+
+/**
+ * Main SDK entry point. Works in Node 18+ and any modern browser.
+ *
+ *   const { OASISClient } = require('@oasisomniverse/web4-api');
+ *   const oasis = new OASISClient({ baseUrl: 'https://api.oasisweb4.one' });
+ *   await oasis.auth.login({ username: 'me@example.com', password: '...' });
+ *   const karma = await oasis.karma.getKarmaForAvatar({ avatarId: oasis.auth.getSession().avatarId });
+ *
+ * Every controller on the OASIS2 ONODE WebAPI is reachable as a lowerCamel
+ * property (oasis.avatar, oasis.data, oasis.karma, oasis.nft, oasis.wallet,
+ * oasis.hyperDrive, oasis.map, oasis.search, ...). Generated methods take a
+ * single args object; route template tokens (e.g. {id}) are consumed from it
+ * automatically, remaining keys become the query string (GET/DELETE) or JSON
+ * body (POST/PUT). oasis.auth is a hand-written convenience wrapper that also
+ * manages the session/token for you.
+ */
+class OASISClient {
+  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);
+
+    // Hand-written ergonomic wrapper, built on top of the generated avatar module.
+    this.auth = new AuthModule(this.http, this.tokenStore, this.avatar);
+  }
+
+  setBaseUrl(baseUrl) {
+    this.http.setBaseUrl(baseUrl);
+  }
+
+  /** Use an externally-issued JWT (e.g. one your server already obtained) for subsequent calls. */
+  setToken(jwtToken, sessionExtras = {}) {
+    this.tokenStore.setSession({ ...sessionExtras, jwtToken });
+  }
+}
+
+module.exports = { OASISClient, HttpClient, TokenStore, DEFAULT_BASE_URL };
+module.exports.default = OASISClient;

package/src/modules/Auth.d.ts

@@ -0,0 +1,28 @@
+// Hand-written type declaration for src/modules/Auth.js
+import type { OASISResponse, OASISSession } from '../core/types';
+
+export interface LoginCredentials {
+  username: string;
+  password: string;
+}
+
+export interface RegisterData {
+  firstName: string;
+  lastName: string;
+  email: string;
+  password: string;
+  confirmPassword?: string;
+  username?: string;
+  avatarType?: string;
+  title?: string;
+  acceptTerms?: boolean;
+}
+
+export declare class AuthModule {
+  constructor(http: unknown, tokenStore: unknown, avatarModule: unknown);
+  getSession(): OASISSession | null;
+  isAuthenticated(): boolean;
+  login(credentials: LoginCredentials): Promise<OASISResponse & { session?: OASISSession }>;
+  register(data: RegisterData): Promise<OASISResponse & { session?: OASISSession }>;
+  logout(): Promise<void>;
+}

package/src/modules/Auth.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Hand-written ergonomic auth wrapper. Built on top of the generated
+ * AvatarModule (api/avatar/authenticate, /register, /revoke-token) and
+ * manages the SDK's TokenStore automatically on login/logout - this is
+ * the one place callers don't have to think about JWTs themselves.
+ */
+class AuthModule {
+  constructor(http, tokenStore, avatarModule) {
+    this._http = http;
+    this._tokenStore = tokenStore;
+    this._avatar = avatarModule;
+  }
+
+  /** Returns the currently stored session ({ avatarId, username, email, jwtToken, ... }) or null. */
+  getSession() {
+    return this._tokenStore.getSession();
+  }
+
+  isAuthenticated() {
+    return Boolean(this._tokenStore.getToken());
+  }
+
+  /**
+   * @param {{username: string, password: string}} credentials `username` may also be an email,
+   *   OASIS' authenticate endpoint accepts either.
+   */
+  async login({ username, password }) {
+    const res = await this._avatar.authenticate({ Username: username, Password: password });
+    if (res.isError || !res.result) return res;
+
+    const avatar = res.result;
+    const session = {
+      avatarId: avatar.id || avatar.Id,
+      username: avatar.username || avatar.Username || username,
+      email: avatar.email || avatar.Email,
+      firstName: avatar.firstName || avatar.FirstName,
+      lastName: avatar.lastName || avatar.LastName,
+      jwtToken: avatar.jwtToken || avatar.JwtToken,
+      refreshToken: avatar.refreshToken || avatar.RefreshToken
+    };
+
+    if (!session.jwtToken) {
+      return { isError: true, message: 'Authentication succeeded but no JWT token was returned.', raw: res.raw };
+    }
+
+    this._tokenStore.setSession(session);
+    return { ...res, session };
+  }
+
+  /**
+   * @param {object} data title, firstName, lastName, email, password, confirmPassword, avatarType, username (optional)
+   */
+  async register(data) {
+    const res = await this._avatar.register({
+      Title: data.title || 'Mx',
+      FirstName: data.firstName,
+      LastName: data.lastName,
+      Email: data.email,
+      Password: data.password,
+      ConfirmPassword: data.confirmPassword || data.password,
+      Username: data.username || data.email,
+      AvatarType: data.avatarType || 'User',
+      AcceptTerms: data.acceptTerms !== false
+    });
+
+    if (res.isError || !res.result) return res;
+
+    const avatar = res.result;
+    const session = {
+      avatarId: avatar.id || avatar.Id,
+      username: avatar.username || avatar.Username,
+      email: avatar.email || avatar.Email,
+      firstName: avatar.firstName || avatar.FirstName,
+      lastName: avatar.lastName || avatar.LastName,
+      jwtToken: avatar.jwtToken || avatar.JwtToken,
+      refreshToken: avatar.refreshToken || avatar.RefreshToken
+    };
+
+    if (session.jwtToken) this._tokenStore.setSession(session);
+    return { ...res, session };
+  }
+
+  async logout() {
+    const token = this._tokenStore.getToken();
+    if (token) {
+      try {
+        await this._avatar.revokeToken({ Token: token });
+      } catch {
+        // Best-effort - always clear the local session regardless of server response.
+      }
+    }
+    this._tokenStore.clear();
+  }
+}
+
+module.exports = { AuthModule };