@arkeytyp/valu-api 1.0.3 → 1.1.1

package/README.md

@@ -1,104 +1,234 @@
-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.
 
-# install
-```
+## Installation
+
+```bash
 npm install @arkeytyp/valu-api
 ```
 
-# Usage
+## Usage
 
-## 1. 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.
+### Initialize ValuApi
+
+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 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 to perform (e.g., `open`, `connect-to-meeting`).
+- **params:** Optional parameters for the action (e.g., room IDs, configuration data).
+
+### Example: Open a Video Chat
+
+```javascript
+import { Intent } from "@arkeytyp/valu-api";
+
+const intent = new Intent('videochat');
+await valuApi.sendIntent(intent);
+```
+
+### 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);
 ```
 
-## 2. 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.
+## Handling Application Lifecycle
+
+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.
+
+This helps you **separate application logic from API wiring** and makes handling incoming intents straightforward.
 
-To get a pointer to the app API version 1:
+### 1. Create Your Application Class
 
 ```javascript
-const appApi = valuApi.getApi('app', 1);
+import { ValuApplication } from '@arkeytyp/valu-api';
+
+class MyApp extends ValuApplication {
+  async onCreate(intent) {
+    console.log('App created with:', intent);
+    return { status: 'initialized' };
+  }
+
+  async onNewIntent(intent) {
+    console.log('New intent received:', intent);
+    return { handled: true, data: { message: 'Processed successfully' } };
+  }
+
+  onDestroy() {
+    console.log('App is shutting down');
+  }
+}
 ```
 
-To use the latest version of the API:
+### 2. Register Your Application with ValuApi
 
 ```javascript
-const appApi = valuApi.current.getApi('app');
+import { ValuApi } from '@arkeytyp/valu-api';
+
+const valuApi = new ValuApi();
+valuApi.setApplication(new MyApp());
 ```
 
-## 3. 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:
+**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.
+
+#### Lifecycle Flow
+
+```
+[onCreate] → [onNewIntent] (0..N times) → [onDestroy]
+```
+
+
+## Using the System API
+
+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:
+
+- 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
+
+Once the API is ready, you can get an `APIPointer` by specifying the API name and (optionally) the version.
 
 ```javascript
-await appApi.run('open', 'text_chat');
+const appApi = await valuApi.getApi('app', 1); // Specific version
+const appApiLatest = await valuApi.getApi('app'); // Latest version
 ```
 
-For interacting with other APIs, like the chat API:
+### 2. Invoke API Commands
+
+After obtaining the API pointer, you can invoke commands.  
+For example, to get the current network id:
 
 ```javascript
-const chatApi = valuApi.current.getApi('chat');
-await chatApi.run('open-channel', { roomId: 'room123', propId: 'prop456' });
+const networkApi = await valuApi.getApi('network');
+const networkId = await networkApi.run('id');
+console.log(networkId);
 ```
 
-## 4. Subscribe to Events
-You can subscribe to events emitted by the API. For example, if you want to listen for the app-open event:
+### 3. Subscribe to Events
+
+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);
 });
 ```
 
-## 5. 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.
+### 4. Run Console Commands (For Testing)
 
-To run a console command, use:
+Use `runConsoleCommand` to execute commands directly in the console environment.
 
 ```javascript
-let command = 'app open text_chat';
-let reply = await valuApi.current.runConsoleCommand(command);
-console.log(reply);
-
-command = 'chat open-channel roomId xz21wd31tx83kk propId 812t26xbq5424b';
-reply = await valuApi.current.runConsoleCommand(command);
+const reply = await valuApi.runConsoleCommand('network id');
 console.log(reply);
 ```
 
-## Example Workflow
-Here's an example of a simple workflow using valu-api:
+#### Run Intents via Console Commands
 
-```javascript
-import { ValuApi } from 'valu-api';
+You can also use the console to run intents — the following two examples achieve the same result:
 
-const valuApi = new ValuApi();
+**Via API:**
 
-// Wait for the API to be ready
-valuApi.current.addEventListener(ValuApi.API_READY, async () => {
-  console.log("API IS READY!!!");
+```javascript
+import { Intent } from "@arkeytyp/valu-api";
 
-  // Get API pointer
-  const appApi = valuApi.current.getApi('app');
+const usersApi = await valuApi.getApi('users');
+const currentUser = await usersApi.run('current');
+if (!currentUser) {
+  console.error('Something went wrong');
+  return;
+}
 
-  // Run a command on the app API
-  await appApi.run('open', 'text_chat');
+const intent = new Intent('textchat', 'open-channel', { userId: currentUser.id });
+await valuApi.sendIntent(intent);
+```
 
-  // Subscribe to events
-  appApi.addEventListener('app-open', (event) => {
-    console.log('App opened:', event);
-  });
+**Via Console:**
 
-  // Run console command for testing
-  let command = 'app open text_chat';
-  let reply = await valuApi.current.runConsoleCommand(command);
-  console.log(reply);
-});
+```javascript
+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);
 ```
 
+## 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.0.3",
+  "version": "1.1.1",
   "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/Intent.js

@@ -0,0 +1,57 @@
+
+export class Intent {
+
+  // Predefined actions
+  static ACTION_VIEW = 'view';
+  static ACTION_OPEN = 'open';
+
+
+  // Private fields
+  #applicationId;
+  #action;
+  #params;
+
+  /** @returns {string} */
+  get applicationId() {
+    return this.#applicationId;
+  }
+
+  /** @returns {string} */
+  get action() {
+    return this.#action;
+  }
+
+  /** @returns {Object} */
+  get params() {
+    return this.#params;
+  }
+
+
+
+  constructor(applicationId, action = Intent.ACTION_OPEN, params = {}) {
+    this.#applicationId = applicationId;
+    this.#action = action;
+    this.#params = params;
+  }
+
+  /**
+   * Validates if a given object is a valid Intent instance.
+   * @param {any} obj
+   * @returns {boolean}
+   */
+  static isValid(obj) {
+    return (
+      obj instanceof Intent &&
+      typeof obj.applicationId === 'string' &&
+      typeof obj.action === 'string'
+    );
+  }
+
+  /**
+   * Returns a stringified representation of the intent.
+   * @returns {string}
+   */
+  toString() {
+    return `[Intent] applicationId="${this.applicationId}", action="${this.action}", params=${JSON.stringify(this.params)}`;
+  }
+}

package/src/ValuApi.js

@@ -1,6 +1,11 @@
 import {EventEmitter} from "./EventEmitter.js";
 import {APIPointer} from "./APIPointer.js";
 import {guid4, nextId} from "./Utils.js";
+import {Intent} from "./Intent";
+
+export { ValuApplication } from "./ValuApplication.js";
+export { Intent } from "./Intent.js";
+export { APIPointer } from "./APIPointer.js";
 
 
 /**
@@ -16,6 +21,11 @@ export class ValuApi {
   #eventEmitter;
   #valuApplication = {};
   #requests = new Map();
+  #lastIntent;
+
+  /** @type ValuApplication */
+  #applicationInstance = null;
+
 
   get connected() {
     return this.#valuApplication.origin !== undefined;
@@ -58,6 +68,21 @@ export class ValuApi {
     return apiPointer;
   }
 
+  /**
+   * Registers an application instance to handle lifecycle events.
+   *
+   * Developers should create a class that extends {@link ValuApplication} and implement
+   * its lifecycle methods.
+   * This instance will receive all lifecycle callbacks sent from the Valu Social host application.
+   */
+  setApplication(appInstance) {
+    this.#applicationInstance = appInstance;
+
+    if(this.#lastIntent) {
+      this.#applicationInstance.onCreate(this.#lastIntent).catch(console.error);
+    }
+  }
+
   async #registerApiPointer(apiName, version, guid) {
     let deferredPromise = this.#createDeferred();
 
@@ -74,8 +99,6 @@ export class ValuApi {
 
   #postToValuApp(name, message) {
      const data = { name: name, message: message};
-
-    // console.log('Posting to Valu: ', name, ' ', message, ' source: ', this.#valuApplication.source);
      this.#valuApplication.source.postMessage(data, this.#valuApplication.origin);
   }
 
@@ -91,6 +114,51 @@ export class ValuApi {
     });
   }
 
+  /**
+   * Sends an intent to the Valu application.
+   *
+   * This method posts the intent data to the Valu application and returns a promise
+   * that resolves or rejects when the corresponding response is received.
+   *
+   * Internally, it creates a deferred promise and assigns a unique `requestId` to track
+   * the response for this specific intent execution.
+   *
+   * @param {Intent} intent - The intent object containing the target application ID, action, and parameters.
+   * @returns {Promise<unknown>} A promise that resolves with the response from the Valu application.
+   *
+   * @example
+   * const intent = new Intent('chatApp', Intent.ACTION_OPEN, { roomId: '1234' });
+   * const result = await api.sendIntent(intent);
+   * console.log(result);
+   */
+  async sendIntent(intent) {
+    let deferredPromise = this.#createDeferred();
+
+    this.#postToValuApp('api:run-intent', {
+      applicationId: intent.applicationId,
+      action: intent.action,
+      params: intent.params,
+      requestId: deferredPromise.id,
+    });
+
+    this.#requests[deferredPromise.id] = deferredPromise;
+    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.
    *
@@ -133,23 +201,33 @@ 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': {
         this.#valuApplication = {
-          id : message,
+          id : message.applicationId,
           source: event.source,
           origin: event.origin,
         }
 
         this.#eventEmitter.emit(ValuApi.API_READY);
+
+        const intent = new Intent(message.applicationId, message.action, message.params);
+        this.#applicationInstance?.onCreate(intent);
+        this.#lastIntent = intent;
         break;
       }
 
+      case 'api:new-intent': {
+        const intent = new Intent(message.applicationId, message.action, message.params);
+        this.#applicationInstance?.onNewIntent(intent);
+      }
+
       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

@@ -0,0 +1,31 @@
+
+/**
+ * Abstract base class for Valu iframe applications.
+ *
+ * Developers should extend this class to implement application-specific logic
+ * for handling lifecycle events within the Valu Social ecosystem.
+ *
+ * The Valu API will automatically call these lifecycle methods when the host
+ * application sends corresponding events (e.g., app launch, new intent, destroy).
+ */
+
+export class ValuApplication {
+  /**
+   * Called when the app is first launched with an Intent.
+   * @param {Intent} intent
+   * @returns {Promise<any>}
+   */
+  async onCreate(intent) {}
+
+  /**
+   * Called when the app receives an Intent while already running (docked).
+   * @param {Intent} intent
+   * @returns {Promise<any>} - The result will be sent back to the caller
+   */
+  async onNewIntent(intent) {}
+
+  /**
+   * Called when the app is about to be destroyed.
+   */
+  async onDestroy() {}
+}

package/types/valu-api.d.ts

@@ -4,6 +4,20 @@ declare module '@arkeytyp/valu-api' {
 
         get connected(): boolean;
 
+        /**
+         * Registers an application instance to handle lifecycle events.
+         * @param appInstance An instance of a class extending ValuApplication.
+         */
+        setApplication(appInstance: ValuApplication): void;
+
+        /**
+         * Sends an intent to another Valu application and returns the response.
+         * @param intent The Intent object containing the target application ID, action, and parameters.
+         * @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>;
@@ -19,4 +33,79 @@ declare module '@arkeytyp/valu-api' {
         removeEventListener(event: string, callback: (data: any) => void): void;
         run(functionName: string, params?: any): Promise<any>;
     }
+
+    export type IntentParams = Record<string, any>;
+
+    export class Intent {
+        // Predefined actions
+        static ACTION_VIEW: string;
+        static ACTION_OPEN: string;
+
+        // Fields
+        private readonly _applicationId: string;
+        private readonly _action: string;
+        private readonly _params: IntentParams;
+
+        /**
+         * @param applicationId The ID of the application this intent targets.
+         * @param action The action to perform (defaults to 'open').
+         * @param params Optional parameters for the action.
+         */
+        constructor(applicationId: string, action?: string, params?: IntentParams);
+
+        /** Application ID this intent targets */
+        get applicationId(): string;
+
+        /** Action this intent performs */
+        get action(): string;
+
+        /** Additional parameters for this intent */
+        get params(): IntentParams;
+
+        /**
+         * Validates if a given object is a valid Intent instance.
+         * @param obj Any object to validate.
+         * @returns True if the object is a valid Intent instance.
+         */
+        static isValid(obj: any): boolean;
+
+        /**
+         * Returns a stringified representation of the intent.
+         */
+        toString(): string;
+    }
+
+    /**
+     * Abstract base class for Valu iframe applications.
+     *
+     * Developers should extend this class to implement application-specific logic
+     * for handling lifecycle events within the Valu Social ecosystem.
+     *
+     * The Valu API will automatically call these lifecycle methods when the host
+     * application sends corresponding events (e.g., app launch, new intent, destroy).
+     */
+    export class ValuApplication {
+        /**
+         * Called when the app is first launched with an Intent.
+         *
+         * @param intent - The Intent that triggered the app launch.
+         * @returns A value or a Promise resolving to a value that will be sent back to the caller.
+         */
+        onCreate(intent: Intent): Promise<any> | any;
+
+        /**
+         * Called when the app receives an Intent while already running (docked).
+         *
+         * @param intent - The incoming Intent.
+         * @returns A value or a Promise resolving to a value that will be sent back to whoever triggered the Intent.
+         */
+        onNewIntent(intent: Intent): Promise<any> | any;
+
+        /**
+         * Called when the app is about to be destroyed.
+         *
+         * Use this to clean up resources (e.g., closing connections, clearing timers).
+         */
+        onDestroy(): void;
+    }
 }