signal-bridge 1.0.4 → 1.0.6

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

@@ -37,5 +37,11 @@ declare function setupBridge(appId: string, options: BridgeOptions): {
     emit(type: string, payload: any): void;
     destroy(): void;
 };
+declare function initBridge(appId: string, options: BridgeOptions): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
 
-export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, resetBridge, setupBridge, signalBridge };
+export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, initBridge, resetBridge, setupBridge, signalBridge };

package/dist/index.d.ts

@@ -37,5 +37,11 @@ declare function setupBridge(appId: string, options: BridgeOptions): {
     emit(type: string, payload: any): void;
     destroy(): void;
 };
+declare function initBridge(appId: string, options: BridgeOptions): {
+    init(): void;
+    listen(handler: Listener): void;
+    emit(type: string, payload: any): void;
+    destroy(): void;
+};
 
-export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, resetBridge, setupBridge, signalBridge };
+export { base64UrlDecode, base64UrlEncode, createBridge, decrypt, encrypt, generateKey, initBridge, resetBridge, setupBridge, signalBridge };

package/dist/index.global.js

@@ -6633,6 +6633,7 @@ var signalBridge = (() => {
     decrypt: () => decrypt,
     encrypt: () => encrypt,
     generateKey: () => generateKey,
+    initBridge: () => initBridge,
     resetBridge: () => resetBridge,
     setupBridge: () => setupBridge,
     signalBridge: () => signalBridge
@@ -6779,17 +6780,21 @@ var signalBridge = (() => {
       }
     };
   }
+  function initBridge(appId, options) {
+    const instance = createBridge(appId, options);
+    instance.init();
+    return instance;
+  }
   if (typeof window !== "undefined") {
-    window.SignalBridge = {
-      setupBridge,
+    window.signalBridge = Object.assign(signalBridge, {
+      init: initBridge,
+      // 👈 pakai ini (auto init)
       createBridge,
-      // 👈 NEW
-      signalBridge,
-      // 👈 NEW
+      reset: resetBridge,
       encrypt,
       decrypt,
       generateKey
-    };
+    });
   }
   return __toCommonJS(index_exports);
 })();