signal-bridge 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,249 @@
+# 🚀 Signal Bridge
+
+Lightweight communication bridge berbasis `window.postMessage` untuk komunikasi **Host ↔ Iframe (Remote App)** dengan fitur:
+
+* 🔐 Optional encryption (AES)
+* 🛡️ Origin validation (security)
+* 🔁 Listener & emitter sederhana
+* ♻️ Singleton instance (init hanya sekali)
+* 🌐 Support UMD (browser global) + npm package
+
+---
+
+## 📦 Installation
+
+```bash
+npm install signal-bridge
+```
+
+atau via CDN (UMD):
+
+```html
+<script src="signal-bridge.umd.js"></script>
+```
+
+---
+
+## ⚙️ Konsep Dasar
+
+Bridge ini digunakan untuk komunikasi antara:
+
+* **Host App** (parent window)
+* **Remote App** (iframe)
+
+⚠️ Library ini **hanya berjalan di dalam iframe (remote)**.
+
+---
+
+## 🧠 API Overview
+
+### 1. Create Bridge (Singleton)
+
+```ts
+import { createBridge } from "signal-bridge";
+
+const bridge = createBridge("my-app-id", {
+  allowedHostOrigins: ["https://host.com"],
+  cryptoKey: "SECRET_KEY", // optional
+  debug: true
+});
+```
+
+> Hanya akan dibuat **1x (singleton)**. Jika dipanggil ulang, akan reuse instance lama.
+
+---
+
+### 2. Init Bridge
+
+```ts
+bridge.init();
+```
+
+Mengirim sinyal `"ready"` ke host.
+
+---
+
+### 3. Emit Event ke Host
+
+```ts
+bridge.emit("login", {
+  userId: 123,
+  token: "abc"
+});
+```
+
+---
+
+### 4. Listen Event dari Host
+
+```ts
+bridge.listen((message) => {
+  console.log("Received:", message);
+
+  if (message.type === "logout") {
+    // handle logout
+  }
+});
+```
+
+---
+
+### 5. Akses Global Instance
+
+Jika ingin akses dari mana saja:
+
+```ts
+import { signalBridge } from "signal-bridge";
+
+signalBridge().emit("ping", {});
+```
+
+⚠️ Pastikan sudah `createBridge().init()` sebelumnya.
+
+---
+
+### 6. Reset Bridge
+
+```ts
+import { resetBridge } from "signal-bridge";
+
+resetBridge();
+```
+
+---
+
+## 🔐 Security Features
+
+### ✅ Origin Validation
+
+```ts
+allowedHostOrigins: ["https://host.com"]
+```
+
+Hanya origin ini yang bisa kirim message ke iframe.
+
+---
+
+### ✅ Encryption (Optional)
+
+```ts
+cryptoKey: "SECRET_KEY"
+```
+
+Payload akan otomatis:
+
+* Encrypt saat `emit`
+* Decrypt saat `receive`
+
+---
+
+## 📡 Message Format
+
+```ts
+type BridgeMessage = {
+  type: string;
+  payload: any;
+  txn: string;
+  __source: "host" | "remote";
+  __origin?: string;
+};
+```
+
+---
+
+## 🌍 Browser (UMD) Usage
+
+```html
+<script>
+  const bridge = window.SignalBridge.createBridge("app-id", {
+    allowedHostOrigins: ["https://host.com"]
+  });
+
+  bridge.init();
+
+  bridge.listen((msg) => {
+    console.log(msg);
+  });
+
+  bridge.emit("hello", { foo: "bar" });
+</script>
+```
+
+---
+
+## 🧪 Example Flow
+
+### Remote (Iframe)
+
+```ts
+const bridge = createBridge("child-app", {
+  allowedHostOrigins: ["https://parent.com"]
+});
+
+bridge.init();
+
+bridge.listen((msg) => {
+  if (msg.type === "user-data") {
+    console.log("User:", msg.payload);
+  }
+});
+
+bridge.emit("ready", { status: "ok" });
+```
+
+---
+
+## ⚠️ Important Notes
+
+* ❗ Harus dijalankan di dalam iframe
+* ❗ `init()` hanya akan trigger sekali (anti duplicate)
+* ❗ Pastikan origin host sesuai (tidak akan menerima jika tidak match)
+* ❗ Encryption hanya aktif jika `cryptoKey` di-set
+
+---
+
+## 🛠️ Available Exports
+
+```ts
+createBridge
+signalBridge
+resetBridge
+encrypt
+decrypt
+generateKey
+```
+
+---
+
+## 🧩 Internal Behavior
+
+* Singleton global instance (`globalBridge`)
+* Anti loop message (`__source` check)
+* Auto ignore invalid message
+* Optional debug logger
+
+---
+
+## 📄 Source
+
+Implementasi utama bisa dilihat di file:
+
+
+
+---
+
+## 🧑‍💻 Author Notes
+
+Dirancang untuk kebutuhan komunikasi microfrontend / iframe integration dengan fokus:
+
+* Simple API
+* Secure by default
+* Minimal dependency
+
+---
+
+## 📜 License
+
+MIT License © 2026 - EkaHersada  
+
+---

package/dist/index.d.mts

@@ -18,11 +18,24 @@ interface BridgeOptions {
     debug?: boolean;
     enableNavigationSync?: boolean;
 }
-declare function signalBridge(appId: string, options: BridgeOptions): {
+declare function createBridge(appId: string, options: BridgeOptions): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
+declare function resetBridge(): void;
+declare function signalBridge(): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
+declare function setupBridge(appId: string, options: BridgeOptions): {
     init(): void;
     listen(handler: Listener): void;
     emit(type: string, payload: any): void;
     destroy(): void;
 };
 
-export { base64UrlDecode, base64UrlEncode, decrypt, encrypt, generateKey, signalBridge };
+export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, resetBridge, setupBridge, signalBridge };

package/dist/index.d.ts

@@ -18,11 +18,24 @@ interface BridgeOptions {
     debug?: boolean;
     enableNavigationSync?: boolean;
 }
-declare function signalBridge(appId: string, options: BridgeOptions): {
+declare function createBridge(appId: string, options: BridgeOptions): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
+declare function resetBridge(): void;
+declare function signalBridge(): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
+declare function setupBridge(appId: string, options: BridgeOptions): {
     init(): void;
     listen(handler: Listener): void;
     emit(type: string, payload: any): void;
     destroy(): void;
 };
 
-export { base64UrlDecode, base64UrlEncode, decrypt, encrypt, generateKey, signalBridge };
+export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, resetBridge, setupBridge, signalBridge };

package/dist/index.global.js

@@ -6629,9 +6629,12 @@ var signalBridge = (() => {
   __export(index_exports, {
     base64UrlDecode: () => base64UrlDecode,
     base64UrlEncode: () => base64UrlEncode,
+    createBridge: () => createBridge,
     decrypt: () => decrypt,
     encrypt: () => encrypt,
     generateKey: () => generateKey,
+    resetBridge: () => resetBridge,
+    setupBridge: () => setupBridge,
     signalBridge: () => signalBridge
   });
 
@@ -6675,7 +6678,33 @@ var signalBridge = (() => {
 
   // src/index.ts
   var isInitialized = false;
-  function signalBridge(appId, options) {
+  var globalConfig = null;
+  var globalBridge = null;
+  function createBridge(appId, options) {
+    if (globalBridge) {
+      if ((globalConfig == null ? void 0 : globalConfig.appId) !== appId || JSON.stringify(globalConfig == null ? void 0 : globalConfig.origins) !== JSON.stringify(options.allowedHostOrigins)) {
+        console.warn("\u26A0\uFE0F Bridge already initialized with different config");
+      }
+      return globalBridge;
+    }
+    globalConfig = {
+      appId,
+      origins: options.allowedHostOrigins
+    };
+    globalBridge = setupBridge(appId, options);
+    return globalBridge;
+  }
+  function resetBridge() {
+    globalBridge == null ? void 0 : globalBridge.destroy();
+    globalBridge = null;
+  }
+  function signalBridge() {
+    if (!globalBridge) {
+      throw new Error("\u274C Bridge belum di-init. Panggil createBridge().init() dulu");
+    }
+    return globalBridge;
+  }
+  function setupBridge(appId, options) {
     const { allowedHostOrigins, cryptoKey, debug } = options;
     const isRemote = window.parent && window.parent !== window;
     if (!isRemote) {
@@ -6699,14 +6728,14 @@ var signalBridge = (() => {
       const remoteMessage = {
         type: data.type,
         payload,
-        txn: data.txn,
+        txn: data.txn || "",
         __source: "host",
         __origin: origin
       };
       listeners.forEach((fn) => fn(remoteMessage));
     };
     window.addEventListener("message", messageHandler);
-    function emitToHost(type, payload) {
+    function emitToHost(type, payload, txn) {
       let finalPayload = payload;
       if (cryptoKey) {
         finalPayload = encrypt(payload, cryptoKey);
@@ -6715,7 +6744,7 @@ var signalBridge = (() => {
         app_id: appId,
         type,
         payload: finalPayload,
-        txn: generateKey(),
+        txn: txn || "",
         __origin: window.location.origin,
         __source: "remote"
       };
@@ -6752,7 +6781,10 @@ var signalBridge = (() => {
   }
   if (typeof window !== "undefined") {
     window.SignalBridge = {
+      createBridge,
+      // 👈 NEW
       signalBridge,
+      // 👈 NEW
       encrypt,
       decrypt,
       generateKey