@arkeytyp/valu-api 1.0.3 → 1.1.0

package/README.md

@@ -1,14 +1,16 @@
 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.
 
-# install
-```
+# Installation
+
+```bash
 npm install @arkeytyp/valu-api
 ```
 
 # 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 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.
 
 ```javascript
 import { ValuApi } from 'valu-api';
@@ -19,23 +21,113 @@ valuApi.current.addEventListener(ValuApi.API_READY, async (e) => {
 });
 ```
 
-## 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.
+# 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.
+
+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).
+
+Here’s an example of creating and running an intent to connect to a video meeting:
+
+```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
+  }
+);
+
+await valuApi.sendIntent(intent);
+```
+
+# Handling Application Lifecycle
+
+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.
+
+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.
+
+## 1. Create Your Application Class
+
+Extend the `ValuApplication` class and override its lifecycle methods:
+
+```javascript
+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' } };
+  }
+
+  async onDestroy() {
+    console.log('App is shutting down');
+  }
+}
+```
+
+## 2. Register Your Application with ValuApi
 
-To get a pointer to the app API version 1:
+Set your application instance within `ValuApi`:
 
 ```javascript
-const appApi = valuApi.getApi('app', 1);
+import { ValuApi } from '@arkeytyp/valu-api';
+
+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
+
+* **`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
+
 ```
+[onCreate] → [onNewIntent] (many times) → [onDestroy]
+```
+
+# Using System API
 
-To use the latest version of the 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:
+
+* 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
+
+This makes it easy to extend the functionality of Valu Social and integrate your iframe application with other parts of the ecosystem.
+
+## 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.
 
 ```javascript
-const appApi = valuApi.current.getApi('app');
+const appApi = valuApi.getApi('app', 1); // Specific version
+const appApiLatest = valuApi.current.getApi('app'); // Latest version
 ```
 
-## 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:
+## 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:
 
 ```javascript
 await appApi.run('open', 'text_chat');
@@ -48,8 +140,9 @@ const chatApi = valuApi.current.getApi('chat');
 await chatApi.run('open-channel', { roomId: 'room123', propId: 'prop456' });
 ```
 
-## 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, if you want to listen for the `app-open` event:
 
 ```javascript
 appApi.addEventListener('app-open', (event) => {
@@ -57,10 +150,9 @@ appApi.addEventListener('app-open', (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:
+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.
 
 ```javascript
 let command = 'app open text_chat';
@@ -73,32 +165,25 @@ console.log(reply);
 ```
 
 ## Example Workflow
-Here's an example of a simple workflow using valu-api:
 
 ```javascript
 import { ValuApi } from 'valu-api';
 
 const valuApi = new ValuApi();
 
-// Wait for the API to be ready
 valuApi.current.addEventListener(ValuApi.API_READY, async () => {
   console.log("API IS READY!!!");
 
-  // Get API pointer
   const appApi = valuApi.current.getApi('app');
 
-  // Run a command on the app API
   await appApi.run('open', 'text_chat');
 
-  // Subscribe to events
   appApi.addEventListener('app-open', (event) => {
     console.log('App opened:', event);
   });
 
-  // Run console command for testing
   let command = 'app open text_chat';
   let reply = await valuApi.current.runConsoleCommand(command);
   console.log(reply);
 });
-```
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkeytyp/valu-api",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "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,37 @@ 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;
+  }
+
   /**
    * Executes a given console command and returns the result of an API function.
    *
@@ -138,15 +192,24 @@ export class ValuApi {
     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];

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,19 @@ 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>;
+
         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 +32,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;
+    }
 }