@arkeytyp/valu-api 1.1.1 → 1.1.3

package/README.md

@@ -225,6 +225,190 @@ const reply = await valuApi.runConsoleCommand(
 console.log(reply);
 ```
 
+# Routing in Valu iFrame Applications
+
+Valu Social allows third‑party developers to register **mini‑applications** that are rendered inside the platform using **iframes**.
+
+Each mini‑app:
+
+* Has a unique **application ID / slug**
+* Is mounted under a dedicated URL namespace in Valu Social
+* Can manage its own internal routing (for example using React Router)
+
+The host application (Valu Social) and the iframe application must stay **route‑synchronized** to ensure:
+
+* Correct deep‑linking
+* Proper browser navigation (back / forward)
+* Shareable URLs
+
+---
+
+## Application Configuration
+
+A mini‑application is registered with a configuration similar to the following:
+
+```json
+{
+  "id": "demo-app",
+  "slug": "demo-app",
+  "iframe": {
+    "url": "https://sample.texpo.io"
+  }
+}
+```
+
+Key fields:
+
+* **id / slug** – determines the public URL under valu-social.com
+* **iframe.url** – the base URL loaded inside the iframe
+
+---
+
+## Host → Iframe Route Mapping
+
+Valu Social automatically maps routes from the host URL to the iframe URL.
+
+### Base Route
+
+When a user opens:
+
+```
+https://valu-social.com/demo-app
+```
+
+Valu Social loads the iframe at:
+
+```
+https://sample.texpo.io/
+```
+
+---
+
+### Nested Routes
+
+When a user opens:
+
+```
+https://valu-social.com/demo-app/page/1
+```
+
+Valu Social loads the iframe at:
+
+```
+https://sample.texpo.io/page/1
+```
+
+📌 **Rule:**
+
+```
+/valu-social/<app-slug>/<path>
+→
+<iframe-base-url>/<path>
+```
+
+No additional configuration is required for this behavior.
+
+---
+
+## Iframe → Host Route Synchronization
+
+If your mini‑application uses **client‑side routing** (for example React Router), route changes **inside the iframe** are not automatically reflected in the Valu Social URL.
+
+To keep the host URL in sync, your app must explicitly report route changes using:
+
+```ts
+valuApi.pushRoute(pathname);
+```
+
+This ensures:
+
+* The browser URL updates correctly
+* Deep links work as expected
+* Page refresh restores the correct internal state
+
+---
+
+## React Router Integration (Recommended)
+
+### Valu Router Bridge Component
+
+Below is a small helper component that listens for route changes and reports them to Valu Social.
+
+```ts
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+import { useValuAPI } from "@/Hooks/useValuApi";
+
+export function ValuRouterBridge() {
+  const valuApi = useValuAPI();
+  const { pathname } = useLocation();
+
+  // Iframe → Host
+  useEffect(() => {
+    if (!valuApi) return;
+    valuApi.pushRoute(pathname);
+  }, [valuApi, pathname]);
+
+  return null;
+}
+```
+
+What this does:
+
+* Listens to internal route changes via `useLocation()`
+* Pushes the current pathname to Valu Social
+* Keeps host and iframe URLs aligned
+
+---
+
+## Example Application Setup
+
+Below is an example of how the bridge is used inside a React application with React Router:
+
+```tsx
+export default function Home() {
+  return (
+    <BrowserRouter>
+      <ValuRouterBridge />
+
+      <div className="flex flex-col min-h-screen">
+        <TopBar isIFrame={false} />
+
+        <main className="flex-grow w-full px-4 py-8">
+          <div className="max-w-[1400px] mx-auto">
+            <Routes>
+              <Route path="/" element={<Navigate to="/console" replace />} />
+
+              <Route
+                path="/console"
+                element={
+                  <>
+                    <Console />
+                    <SampleApiCalls />
+                  </>
+                }
+              />
+
+              <Route path="/storage" element={<ApplicationStorage />} />
+              <Route path="/documentation" element={<Documentation />} />
+            </Routes>
+          </div>
+        </main>
+
+        <Footer />
+      </div>
+    </BrowserRouter>
+  );
+}
+```
+---
+
+## Best Practices
+
+* Always report route changes using `valuApi.pushRoute`
+* Use relative paths (e.g. `/console`, `/page/1`)
+* Ensure your app can handle being opened directly on any route
+
 ## Sample Project
 
 We've created a sample application integrated with Valu API.  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkeytyp/valu-api",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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

@@ -1,7 +1,7 @@
 import {EventEmitter} from "./EventEmitter.js";
 import {APIPointer} from "./APIPointer.js";
 import {guid4, nextId} from "./Utils.js";
-import {Intent} from "./Intent";
+import {Intent} from "./Intent.js";
 
 export { ValuApplication } from "./ValuApplication.js";
 export { Intent } from "./Intent.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 = {};
@@ -184,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) => {
@@ -219,9 +254,20 @@ 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': {
@@ -265,4 +311,4 @@ export class ValuApi {
       }
     }
   }
-}
+}

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;
 
@@ -22,6 +23,27 @@ declare module '@arkeytyp/valu-api' {
         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 {
@@ -107,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;
     }
 }