@arkeytyp/valu-api 1.1.0 → 1.1.1

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);
+```
+
+### 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.
+
+---
 
-# Handling Application Lifecycle
+### 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,103 @@ 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 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
+#### 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.
+## Using the System API
 
-This API provides a unified way to:
+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 specific commands on these features
-* Subscribe to real-time events emitted by the platform
-* Run and test commands from the console for debugging
+- 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
 
-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
 
-## 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:
+### 3. Subscribe to Events
 
-```javascript
-const chatApi = valuApi.current.getApi('chat');
-await chatApi.run('open-channel', { roomId: 'room123', propId: 'prop456' });
-```
-
-## 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);
-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
+#### 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 { ValuApi } from 'valu-api';
+import { Intent } from "@arkeytyp/valu-api";
 
-const valuApi = new ValuApi();
+const usersApi = await valuApi.getApi('users');
+const currentUser = await usersApi.run('current');
+if (!currentUser) {
+  console.error('Something went wrong');
+  return;
+}
 
-valuApi.current.addEventListener(ValuApi.API_READY, async () => {
-  console.log("API IS READY!!!");
+const intent = new Intent('textchat', 'open-channel', { userId: currentUser.id });
+await valuApi.sendIntent(intent);
+```
 
-  const appApi = valuApi.current.getApi('app');
+**Via Console:**
 
-  await appApi.run('open', 'text_chat');
+```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);
+```
 
-  appApi.addEventListener('app-open', (event) => {
-    console.log('App opened:', event);
-  });
+## Sample Project
 
-  let command = 'app open text_chat';
-  let reply = await valuApi.current.runConsoleCommand(command);
-  console.log(reply);
-});
-```
+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.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/ValuApi.js

@@ -145,6 +145,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.
    *
@@ -187,7 +201,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': {
@@ -213,6 +227,7 @@ export class ValuApi {
       case 'api:run-console-completed': {
         const requestId = event.data.requestId;
         const deferred = this.#requests[requestId];
+
         if(deferred) {
           deferred.resolve(message);
         } else {

package/types/valu-api.d.ts

@@ -16,6 +16,7 @@ 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;