@arkeytyp/valu-api 1.1.0 → 1.1.2

package/README.md

@@ -1,62 +1,107 @@
-The `valu-api` package enables developers to create custom iframe applications for Valu Social. It provides tools to invoke functions of registered Valu applications and subscribe to their events. With features like API versioning, event handling, and console command testing, developers can seamlessly integrate and extend functionality within the Valu Social ecosystem.
+The `valu-api` package enables developers to build custom iframe applications for Valu Social.  
+It provides tools to invoke functions on registered Valu applications, subscribe to their events, and communicate via intents.  
+With features like API versioning, event handling, and console command execution, you can seamlessly integrate and extend functionality within the Valu Social ecosystem.
 
-# Installation
+## Installation
 
 ```bash
 npm install @arkeytyp/valu-api
 ```
 
-# Usage
+## Usage
 
-## Initialize ValuApi
+### Initialize ValuApi
 
-On your application startup, create an instance of `ValuApi` and subscribe to the `API_READY` event. This event will be triggered only when your application is launched as an iframe within the Valu Verse application.
+On application startup, create an instance of `ValuApi` and subscribe to the `API_READY` event.  
+This event is triggered only when your application is launched as an iframe within the Valu Verse application.
 
 ```javascript
-import { ValuApi } from 'valu-api';
+import { ValuApi } from "@arkeytyp/valu-api";
 
 const valuApi = new ValuApi();
-valuApi.current.addEventListener(ValuApi.API_READY, async (e) => {
-  console.log("API IS READY!!!");
+valuApi.addEventListener(ValuApi.API_READY, async (e) => {
+  console.log("API IS READY!");
 });
 ```
 
-# Running Application Intents
 
-Intents are a powerful way to communicate with other applications inside the Valu Social ecosystem. They allow your application to request actions from other registered Valu apps in a standardized way — for example, opening a chat, joining a meeting, or performing any predefined operation supported by another app.
+## Running Application Intents
+
+Intents are a powerful way to communicate with other applications inside Valu Social.  
+They allow your application to request actions from other registered apps in a standardized way — for example, opening a chat, joining a meeting, or performing any supported operation.
 
 Each Intent contains:
 
-* **applicationId:** The target application’s ID.
-* **action:** The action you want to perform (e.g., `open`, `connect-to-meeting`).
-* **params:** Optional parameters for the action (e.g., room IDs, configuration data).
+- **applicationId:** The target application’s ID.
+- **action:** The action to perform (e.g., `open`, `connect-to-meeting`).
+- **params:** Optional parameters for the action (e.g., room IDs, configuration data).
 
-Here’s an example of creating and running an intent to connect to a video meeting:
+### Example: Open a Video Chat
 
 ```javascript
-import { Intent } from 'valu-api';
-
-const intent = new Intent(
-  'videochat',              // Target application ID
-  'connect-to-meeting',     // Action to perform
-  {
-    roomId: '<room-id>',    // Additional parameters
-    withLocalTracks: true
-  }
-);
+import { Intent } from "@arkeytyp/valu-api";
 
+const intent = new Intent('videochat');
 await valuApi.sendIntent(intent);
 ```
 
-# Handling Application Lifecycle
+### Example: Open a Text Channel for the Current User
+
+First, get the current user ID using the `users` API:
+
+```javascript
+import { Intent } from "@arkeytyp/valu-api";
+
+const usersApi = await valuApi.getApi('users');
+const currentUser = await usersApi.run('current');
+if (!currentUser) {
+  console.error('Something went wrong');
+  return;
+}
+
+const intent = new Intent('textchat', 'open-channel', { userId: currentUser.id });
+await valuApi.sendIntent(intent);
+```
+## Invoking Services
+
+Invoking a Service works almost the same way as running an Application Intent.  
+You still use the same `Intent` object with `applicationId`, `action`, and optional `params` — the key difference is **what the `applicationId` points to and how the call affects the UI**.
+
+When calling a **Service Intent**:
+
+- **`applicationId`** refers to the **service name** (e.g., `ApplicationStorage`), not a visible UI application.
+- Services run entirely **in the background**.
+- Invoking a service **does not change** the currently opened applications.
+- Service Intents are ideal for performing background logic such as:
+  - Running searches  
+  - Fetching or processing data  
+  - Triggering non-visual workflows  
+  - Performing system-level operations
+
+This makes Services a parallel mechanism to Application Intents, with the difference that they target **non-UI services** instead of interactive apps.
+
+---
+
+### Example: Querying the `ApplicationStorage` Service
+
+Below is an example of using an `Intent` to query the `ApplicationStorage` service to search for resources:
+
+```ts
+const intent = new Intent('ApplicationStorage', 'resource-search', {
+  size: 10,
+});
+
+const result = await valuApi.callService(intent);
+```
 
-The `valu-api` package provides a way to handle **application lifecycle events** inside your iframe application. By implementing a `ValuApplication` class and registering it with `ValuApi`, you can easily respond to events such as when your app is created, receives a new intent, or is destroyed.
+## Handling Application Lifecycle
 
-This allows you to **separate application logic from API wiring** and makes it simple to handle incoming intents and return values back to the caller.
+The `valu-api` package lets your iframe app handle **application lifecycle events**.  
+By extending `ValuApplication` and registering it with `ValuApi`, you can respond when your app is created, receives a new intent, or is destroyed.
 
-## 1. Create Your Application Class
+This helps you **separate application logic from API wiring** and makes handling incoming intents straightforward.
 
-Extend the `ValuApplication` class and override its lifecycle methods:
+### 1. Create Your Application Class
 
 ```javascript
 import { ValuApplication } from '@arkeytyp/valu-api';
@@ -72,15 +117,13 @@ class MyApp extends ValuApplication {
     return { handled: true, data: { message: 'Processed successfully' } };
   }
 
-  async onDestroy() {
+  onDestroy() {
     console.log('App is shutting down');
   }
 }
 ```
 
-## 2. Register Your Application with ValuApi
-
-Set your application instance within `ValuApi`:
+### 2. Register Your Application with ValuApi
 
 ```javascript
 import { ValuApi } from '@arkeytyp/valu-api';
@@ -89,101 +132,199 @@ const valuApi = new ValuApi();
 valuApi.setApplication(new MyApp());
 ```
 
-Once registered, the `ValuApi` will call the appropriate lifecycle methods when events are received from the host (e.g., app launch, new intent, app close).
-
-## Lifecycle Methods
+**Lifecycle Methods:**
+- `onCreate(intent)` — Triggered when the application is first launched with an intent.
+- `onNewIntent(intent)` — Triggered when a new intent is sent while the application is already running.
+- `onDestroy()` — Triggered when the application is about to be destroyed.
 
-* **`onCreate(intent)`** – Triggered when the application is first launched with an Intent. You can return an optional value to send back to the caller.
-* **`onNewIntent(intent)`** – Triggered when a new Intent is sent to the application while it is already running. The return value will be sent back to whoever triggered the Intent.
-* **`onDestroy()`** – Triggered when the application is about to be destroyed. Use this to clean up resources.
-
-### Lifecycle Flow
+#### Lifecycle Flow
 
 ```
-[onCreate] → [onNewIntent] (many times) → [onDestroy]
+[onCreate] → [onNewIntent] (0..N times) → [onDestroy]
 ```
 
-# Using System API
-
-The **System API** allows your iframe application to interact directly with the Valu Social platform and its internal applications.
 
-This API provides a unified way to:
+## Using the System API
 
-* Access core platform features (apps, chat, etc.)
-* Call specific commands on these features
-* Subscribe to real-time events emitted by the platform
-* Run and test commands from the console for debugging
+The **System API** allows your iframe app to interact directly with the Valu Social platform and its internal applications.  
+It provides a unified way to:
 
-This makes it easy to extend the functionality of Valu Social and integrate your iframe application with other parts of the ecosystem.
+- Access core platform features (apps, chat, etc.)
+- Call commands on these features
+- Subscribe to real-time events from the platform
+- Run and test commands from the console for debugging
 
-## 1. Get an API Pointer
+### 1. Get an API Pointer
 
-Once the API is ready, you can create an `APIPointer` instance by specifying the name and version of the API you want to use. The version parameter is optional, and if omitted, the latest version will be used.
+Once the API is ready, you can get an `APIPointer` by specifying the API name and (optionally) the version.
 
 ```javascript
-const appApi = valuApi.getApi('app', 1); // Specific version
-const appApiLatest = valuApi.current.getApi('app'); // Latest version
+const appApi = await valuApi.getApi('app', 1); // Specific version
+const appApiLatest = await valuApi.getApi('app'); // Latest version
 ```
 
-## 2. Invoke API Commands
+### 2. Invoke API Commands
 
-After obtaining the API pointer, you can invoke commands on the API. Here's an example of opening the `text_chat` on the app API:
+After obtaining the API pointer, you can invoke commands.  
+For example, to get the current network id:
 
 ```javascript
-await appApi.run('open', 'text_chat');
+const networkApi = await valuApi.getApi('network');
+const networkId = await networkApi.run('id');
+console.log(networkId);
 ```
 
-For interacting with other APIs, like the chat API:
-
-```javascript
-const chatApi = valuApi.current.getApi('chat');
-await chatApi.run('open-channel', { roomId: 'room123', propId: 'prop456' });
-```
+### 3. Subscribe to Events
 
-## 3. Subscribe to Events
-
-You can subscribe to events emitted by the API. For example, if you want to listen for the `app-open` event:
+You can subscribe to events emitted by the API.  
+For example, listen for the `app-open` event:
 
 ```javascript
+const appApi = await valuApi.getApi('app');
 appApi.addEventListener('app-open', (event) => {
   console.log(event);
 });
 ```
 
-## 4. Run Console Commands (For Testing)
+### 4. Run Console Commands (For Testing)
 
-You can use the `runConsoleCommand` method to execute commands directly in the console environment. This method processes the output and returns a resolved promise on success or an error message if the command fails.
+Use `runConsoleCommand` to execute commands directly in the console environment.
 
 ```javascript
-let command = 'app open text_chat';
-let reply = await valuApi.current.runConsoleCommand(command);
+const reply = await valuApi.runConsoleCommand('network id');
 console.log(reply);
+```
 
-command = 'chat open-channel roomId xz21wd31tx83kk propId 812t26xbq5424b';
-reply = await valuApi.current.runConsoleCommand(command);
-console.log(reply);
+#### Run Intents via Console Commands
+
+You can also use the console to run intents — the following two examples achieve the same result:
+
+**Via API:**
+
+```javascript
+import { Intent } from "@arkeytyp/valu-api";
+
+const usersApi = await valuApi.getApi('users');
+const currentUser = await usersApi.run('current');
+if (!currentUser) {
+  console.error('Something went wrong');
+  return;
+}
+
+const intent = new Intent('textchat', 'open-channel', { userId: currentUser.id });
+await valuApi.sendIntent(intent);
 ```
 
-## Example Workflow
+**Via Console:**
 
 ```javascript
-import { ValuApi } from 'valu-api';
+const currentUser = await valuApi.runConsoleCommand('users current');
+const reply = await valuApi.runConsoleCommand(
+  `app run -applicationId textchat -action open-channel -userId ${currentUser.id}`
+);
+console.log(reply);
+```
 
-const valuApi = new ValuApi();
+# Routing in Valu iFrame Applications
+
+The application is embedded inside Valuverse and controlled by the host.
+
+- Valuverse owns the global routing context
+- Your app receives route updates from Valu
+- Your app should push navigation changes back to Valu
+
+---
+
+## Important Concept: Route Visibility
+
+There are **two different routing scopes**:
+
+### Local (App-only) Routing
+Routing handled only inside your application (e.g. React Router).
+
+- ✅ App works normally
+- ❌ Routes are **not visible** to Valuverse
+- ❌ No deep linking from the main application
+
+### Valu Routing (Host-aware)
+Routing handled through Valu API.
+
+- ✅ Routes appear in the main application
+- ✅ Deep linking works
+- ✅ Navigation state is shared with Valuverse
+
+---
+
+## Using React Router in an iFrame App
+
+Using **React Router inside an iFrame Valu app is totally fine**.
+
+Your application will:
+- render pages correctly
+- navigate normally
+- function as a self-contained UI
 
-valuApi.current.addEventListener(ValuApi.API_READY, async () => {
-  console.log("API IS READY!!!");
+However:
 
-  const appApi = valuApi.current.getApi('app');
+- those routes are **internal only**
+- they **do not propagate** to Valuverse
+- the main application will not see or control them
 
-  await appApi.run('open', 'text_chat');
+This approach is acceptable for:
+- demo applications
+- prototypes
+- isolated tools
+- apps that do not need host-level routing
 
-  appApi.addEventListener('app-open', (event) => {
-    console.log('App opened:', event);
-  });
+---
 
-  let command = 'app open text_chat';
-  let reply = await valuApi.current.runConsoleCommand(command);
-  console.log(reply);
+## Best Practice for Valuverse Applications
+
+If your application is built to behave like a **native Valuverse app**, the recommended approach is:
+
+> **Use Valu routing instead of (or in addition to) local routing.**
+
+This ensures:
+- consistent navigation behavior
+- correct deep linking
+- visibility in the main application router
+- proper docking and context switching
+
+---
+
+## Valu Routing API
+
+### Subscribing to Route Changes
+
+Valu notifies your application when the route changes:
+
+```ts
+valuApi.addEventListener(ValuApi.ON_ROUTE, (route) => {
+  // route example:
+  // "/console"
+  // "/api/users/id/123"
 });
-```
+```
+
+### Pushing a New Route
+
+Navigate forward:
+
+```ts
+valuApi.pushRoute("/documentation");
+```
+
+Replacing the Current Route
+Redirect without adding a history entry:
+
+```ts
+valuApi.replaceRoute("/console");
+```
+
+## Sample Project
+
+We've created a sample application integrated with Valu API.  
+Check out the repository here and feel free to leave comments or feedback:
+
+[https://github.com/Roomful/ValuSampleApp](https://github.com/Roomful/ValuSampleApp)
+know if you want a **quick start** section, more real-world samples, or even a troubleshooting/FAQ block!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkeytyp/valu-api",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A package for developing iframe applications for Valu Social. Allows invoking functions of registered Valu applications and subscribing to events, as well as other features that enable developers creating own ifram apps for the value social",
   "main": "src/ValuApi.js",
   "scripts": {

package/src/ValuApi.js

@@ -17,6 +17,7 @@ export { APIPointer } from "./APIPointer.js";
 export class ValuApi {
 
   static API_READY = 'api:ready'
+  static ON_ROUTE = `on_route`;
 
   #eventEmitter;
   #valuApplication = {};
@@ -145,6 +146,20 @@ export class ValuApi {
     return deferredPromise.promise;
   }
 
+  async callService(intent) {
+    let deferredPromise = this.#createDeferred();
+
+    this.#postToValuApp('api:service-intent', {
+      applicationId: intent.applicationId,
+      action: intent.action,
+      params: intent.params,
+      requestId: deferredPromise.id,
+    });
+
+    this.#requests[deferredPromise.id] = deferredPromise;
+    return deferredPromise.promise;
+  }
+
   /**
    * Executes a given console command and returns the result of an API function.
    *
@@ -170,6 +185,40 @@ export class ValuApi {
     return deferredPromise.promise;
   }
 
+
+  #runCommand(name, data) {
+    this.#postToValuApp('api:run-command', {
+      command: name,
+      data: data,
+    });
+  }
+
+  /**
+   * Pushes a new route onto the navigation stack.
+   *
+   * Use this when:
+   *   navigating forward
+   *   opening a new view
+   *   preserving back-navigation history
+   * @param path
+   */
+  pushRoute = (path) => {
+    this.#runCommand('pushRoute', path);
+  }
+
+  /**
+   * Replaces the current route without adding a new history entry.
+   * Use this when:
+   *    redirecting
+   *    normalizing URLs
+   *    preventing back-navigation to the previous route
+   * @param {string }path
+   */
+  replaceRoute = (path) => {
+    this.#runCommand('replaceRoute', path);
+  }
+
+
   #createDeferred() {
     let resolve, reject;
     const promise = new Promise((res, rej) => {
@@ -187,7 +236,7 @@ export class ValuApi {
     }
 
     const message = event.data.message;
-   // console.log('Message From Valu: ', event.data.name, ' ', message);
+    //console.log('Message From Valu: ', event.data.name, ' ', message);
 
     switch (event.data.name) {
       case 'api:ready': {
@@ -205,14 +254,26 @@ export class ValuApi {
         break;
       }
 
+      case 'api:trigger': {
+        switch (message.action) {
+          case ValuApi.ON_ROUTE: {
+            this.#eventEmitter.emit(ValuApi.ON_ROUTE, message.data);
+            this.#applicationInstance?.onUpdateRouterContext(message.data);
+          }
+        }
+        break;
+      }
+
       case 'api:new-intent': {
         const intent = new Intent(message.applicationId, message.action, message.params);
         this.#applicationInstance?.onNewIntent(intent);
+        break;
       }
 
       case 'api:run-console-completed': {
         const requestId = event.data.requestId;
         const deferred = this.#requests[requestId];
+
         if(deferred) {
           deferred.resolve(message);
         } else {

package/src/ValuApplication.js

@@ -28,4 +28,15 @@ export class ValuApplication {
    * Called when the app is about to be destroyed.
    */
   async onDestroy() {}
+
+
+  /**
+   * Called when the application’s router context changes.
+   *
+   * This typically happens when:
+   *  the app moves between main / side / modal containers
+   *  the host updates routing or layout state
+   * @param {string} context
+   */
+  onUpdateRouterContext(context) {};
 }

package/types/valu-api.d.ts

@@ -1,6 +1,7 @@
 declare module '@arkeytyp/valu-api' {
     export class ValuApi {
         static API_READY: string;
+        static ON_ROUTE : string;
 
         get connected(): boolean;
 
@@ -16,11 +17,33 @@ declare module '@arkeytyp/valu-api' {
          * @returns A promise resolving to the response from the target application.
          */
         sendIntent(intent: Intent): Promise<any>;
+        callService(intent: Intent): Promise<any>;
 
         addEventListener(event: string, callback: (data: any) => void): void;
         removeEventListener(event: string, callback: (data: any) => void): void;
         getApi(apiName: string, version?: number): Promise<APIPointer>;
         runConsoleCommand(command: string): Promise<any | string>;
+
+        /**
+         * Pushes a new route onto the navigation stack.
+         *
+         * Use this when:
+         *   navigating forward
+         *   opening a new view
+         *   preserving back-navigation history
+         * @param path
+         */
+        pushRoute(path: string): void;
+
+        /**
+         * Replaces the current route without adding a new history entry.
+         * Use this when:
+         *    redirecting
+         *    normalizing URLs
+         *    preventing back-navigation to the previous route
+         * @param {string }path
+         */
+        replaceRoute(path: string): void;
     }
 
     export class APIPointer {
@@ -106,5 +129,15 @@ declare module '@arkeytyp/valu-api' {
          * Use this to clean up resources (e.g., closing connections, clearing timers).
          */
         onDestroy(): void;
+
+        /**
+         * Called when the application’s router context changes.
+         *
+         * This typically happens when:
+         *  the app moves between main / side / modal containers
+         *  the host updates routing or layout state
+         * @param context - updated application route
+         */
+        onUpdateRouterContext(context: string): void;
     }
 }