@gcm-cz/dmon-switcher 0.1.0 → 1.0.2

package/README.md

@@ -0,0 +1,244 @@
+# @gcm-cz/dmon-switcher
+
+Headless JavaScript library for integrating the DMon user switcher into a relying party (RP).
+
+Lets your application discover which users the browser has already authenticated with DMon and
+switch between them — without leaving your page, without re-implementing the picker UI, and
+without touching DMon's cookies directly.
+
+Internally the library embeds a hidden `<iframe>` that loads a DMon-hosted bridge page. The
+bridge runs in DMon's first-party context, reads the `dmon_auth` session cookie, and exposes a
+`postMessage` RPC interface. Your application calls `listSessions()`, renders its own picker,
+and calls `switchTo()`. **The library renders no UI of its own.**
+
+Zero runtime dependencies. Ships as ESM + CJS with full TypeScript declarations.
+
+---
+
+## Prerequisites
+
+- A DMon instance with the embed bridge feature enabled.
+- A registered DMon client with **`embed_origins`** configured to include your application's
+  origin (e.g. `https://app.example.com`). Without this, the bridge iframe will be blocked by
+  CSP and the library will not function. See the
+  [RP Integration Guide](../../docs/integrations/RP_USER_SWITCHER.md#4-client-registration)
+  for the admin UI walk-through.
+
+---
+
+## Installation
+
+```sh
+npm install @gcm-cz/dmon-switcher
+# or
+pnpm add @gcm-cz/dmon-switcher
+```
+
+---
+
+## Quickstart
+
+```typescript
+import { DmonSwitcher } from "@gcm-cz/dmon-switcher";
+import type { Session } from "@gcm-cz/dmon-switcher";
+
+// Instantiate once at component mount. A hidden iframe is created immediately.
+const switcher = new DmonSwitcher({
+    dmonOrigin: "https://accounts.example.com",
+    realmSlug: "default",
+    clientId: "my-rp",
+    mode: "emit",   // "emit" (default) or "redirect" — controls switchTo() behaviour
+});
+
+// Register a switch handler before awaiting ready().
+switcher.on("switch", ({ sub }) => {
+    if (sub === "__new__") {
+        // Force interactive login to add a new session.
+        window.location.href = buildAuthorizeUrl({ prompt: "login" });
+        return;
+    }
+    // Attempt silent re-auth; fall back to interactive on login_required.
+    performSilentAuth({ loginHint: sub, prompt: "none" })
+        .catch(() => { window.location.href = buildAuthorizeUrl({ loginHint: sub }); });
+});
+
+// Wait for the bridge to signal ready, then fetch the session list.
+await switcher.ready();
+const sessions: Session[] = await switcher.listSessions();
+renderMyUserMenu(sessions);
+
+// Switch to a user when selected in your menu.
+await switcher.switchTo(selectedSub);
+
+// Build the account-page URL for an anchor — the user decides how to open it.
+const accountHref = switcher.accountPageUrl(currentUserSub);
+// <a href={accountHref}>Account settings</a>
+
+// Clean up when the component unmounts.
+switcher.destroy();
+```
+
+### React example
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import { DmonSwitcher } from "@gcm-cz/dmon-switcher";
+import type { Session } from "@gcm-cz/dmon-switcher";
+
+function UserMenu({ currentSub }: { currentSub: string }) {
+    const switcherRef = useRef<DmonSwitcher | null>(null);
+    const [sessions, setSessions] = useState<Session[]>([]);
+
+    useEffect(() => {
+        const switcher = new DmonSwitcher({
+            dmonOrigin: "https://accounts.example.com",
+            realmSlug: "default",
+            clientId: "my-rp",
+        });
+        switcherRef.current = switcher;
+
+        switcher.on("switch", ({ sub }) => {
+            // your re-auth logic
+        });
+
+        switcher.ready()
+            .then(() => switcher.listSessions())
+            .then(setSessions);
+
+        return () => switcher.destroy();
+    }, []);
+
+    return (
+        <menu>
+            {sessions.map(s => (
+                <li key={s.sub} onClick={() => switcherRef.current?.switchTo(s.sub)}>
+                    {s.name}
+                </li>
+            ))}
+            <li>
+                <a href={switcherRef.current?.accountPageUrl(currentSub)}>
+                    Account settings
+                </a>
+            </li>
+        </menu>
+    );
+}
+```
+
+---
+
+## API Reference
+
+### `Session`
+
+```typescript
+interface Session {
+    sub: string;          // Stable user identifier (OIDC "sub" claim)
+    name: string;         // Display name
+    given_name?: string;
+    family_name?: string;
+    picture?: string;     // Profile picture URL
+}
+```
+
+`listSessions()` returns only sessions the realm's `can_authorize` policy permits. Users
+authenticated in DMon but blocked by policy are silently omitted.
+
+### `DmonSwitcherOptions`
+
+```typescript
+interface DmonSwitcherOptions {
+    dmonOrigin: string;   // Base URL of your DMon instance
+    realmSlug: string;    // Realm slug the RP is registered in
+    clientId: string;     // OAuth 2.0 client_id of the RP
+    mode?: "emit" | "redirect";  // default "emit"
+    debug?: boolean;      // Log internal steps via console.debug; default false
+}
+```
+
+**`debug`** — when `true`, every internal step is logged via `console.debug` under the
+`[DmonSwitcher]` prefix: construction, ready handshake, RPC send/receive, dropped messages,
+switch, account-page URL construction, and teardown. Off by default. Useful during integration
+and troubleshooting; do not enable in production.
+
+### `DmonSwitcher`
+
+#### `constructor(opts: DmonSwitcherOptions)`
+
+Creates a hidden `<iframe>`, appends it to `document.body`, and starts the bridge handshake.
+Does not throw — errors are deferred and surfaced via `ready()` never resolving.
+
+#### `ready(): Promise<void>`
+
+Resolves when the bridge iframe sends its `ready` message. Also resolves immediately if
+construction failed (e.g. DOM unavailable) or after `destroy()` is called — in both cases the
+instance is inoperative and subsequent calls no-op.
+
+`listSessions()` and `switchTo()` in `"redirect"` mode wait for `ready()` internally before
+sending an RPC, so you do not have to await `ready()` before calling them. `switchTo()` in
+`"emit"` mode fires local listeners immediately without waiting for the bridge. Awaiting
+`ready()` explicitly is recommended when you want timeout-based error detection:
+
+```typescript
+const TIMEOUT = 5000;
+await Promise.race([
+    switcher.ready(),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("bridge timeout")), TIMEOUT)),
+]);
+```
+
+#### `listSessions(): Promise<Session[]>`
+
+Sends a `list_sessions` RPC to the bridge. Returns `[]` when there are no authenticated
+sessions, when the cookie is absent, or when all sessions are policy-blocked.
+
+#### `switchTo(sub: string, opts?: { returnTo?: string }): Promise<void>`
+
+Initiates a user switch.
+
+- **`"emit"` mode** — fires all `switch` listeners with `{ sub }` and resolves immediately.
+  The RP is responsible for triggering OIDC re-authentication.
+- **`"redirect"` mode** — sends `redirect_authorize` to the bridge, which top-level-navigates
+  to the DMon `/authorize` endpoint with `login_hint=sub`, `prompt=none`, and
+  `redirect_uri=opts.returnTo ?? window.location.href`.
+
+**`__new__` sentinel:** `switchTo("__new__")` uses `prompt=login` to force fresh credential
+entry and append a new session to the cookie.
+
+#### `accountPageUrl(sub: string): string`
+
+Returns (does **not** open) the DMon account-page URL for `sub`:
+
+```
+{dmonOrigin}/account?login_hint={encodeURIComponent(sub)}
+```
+
+Pure and side-effect free — safe to call during render. Put the result in an anchor `href` so
+the user controls how it opens. DMon will silently mount the account page if the cookie already
+contains the session for `sub`; otherwise it falls back to the standard login flow.
+
+#### `destroy(): void`
+
+Removes the iframe, deregisters `window` message listeners, rejects all pending RPC promises
+with `AbortError`, and resolves any pending `ready()` waiters so they do not hang. Idempotent —
+safe to call multiple times, subsequent calls are no-ops. Call at component unmount.
+
+#### `on(event: "switch", handler: (payload: { sub: string }) => void): void`
+
+Registers a handler fired by `switchTo()` in `"emit"` mode.
+
+#### `on(event: "ready", handler: () => void): void`
+
+Registers a handler called when the bridge sends its `ready` message.
+
+---
+
+## `switchTo` modes
+
+| Mode | What `switchTo()` does | Who triggers re-auth |
+|---|---|---|
+| `"emit"` (default) | Fires the `switch` event | Your code |
+| `"redirect"` | Bridge navigates the page to DMon `/authorize` | DMon → OIDC code callback |
+
+`"emit"` is recommended for SPAs — it keeps your application in control of the authorization
+flow and lets you discard tokens before starting the new grant.

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(s){if(typeof s!="object"||s===null)return!1;const i=s;return!(i.dmon_bridge!==!0||typeof i.type!="string")}function d(s){return typeof s.request_id=="string"}class l{constructor(i){this.iframe=null,this.nextRequestId=1,this.destroyed=!1,this.failed=!1,this.pending=new Map,this.switchListeners=[],this.readyListeners=[],this.handleMessage=e=>{if(this.iframe==null||!h(e.data))return;if(e.source!==this.iframe.contentWindow){this.log("message dropped: wrong source",{eventOrigin:e.origin,expectedOrigin:this.origin,hasSource:e.source!=null,sourceIsExpectedIframe:!1});return}if(e.origin!==this.origin){this.log("message dropped: wrong origin",{eventOrigin:e.origin,expectedOrigin:this.origin});return}const t=e.data;if(t.type==="ready"){this.log("ready received"),this.resolveReady();for(const o of this.readyListeners)try{o()}catch(n){this.logError("ready handler threw",n)}return}if(!d(t)){this.log("message dropped: no request_id");return}const r=this.pending.get(t.request_id);r!==void 0?(this.log("rpc reply",{request_id:t.request_id,type:t.type}),this.pending.delete(t.request_id),r.resolve(t)):this.log("rpc reply for unknown request_id — ignored",{request_id:t.request_id})},this.origin=i.dmonOrigin,this.mode=i.mode??"emit",this.debug=i.debug??!1,this.readyPromise=new Promise(e=>{this.resolveReady=e});try{const e=`${i.dmonOrigin}/api/v1/authorize/${i.realmSlug}/embed/bridge?client_id=${encodeURIComponent(i.clientId)}`,t=document.createElement("iframe");t.setAttribute("aria-hidden","true"),t.setAttribute("sandbox","allow-scripts allow-same-origin"),t.style.display="none",t.src=e,document.body.appendChild(t),this.iframe=t,window.addEventListener("message",this.handleMessage),this.log("constructed",{origin:this.origin,mode:this.mode,src:e})}catch(e){this.failed=!0,this.resolveReady(),this.logError("construction failed — switcher disabled",e)}}ready(){return this.readyPromise}async listSessions(){if(this.failed||this.destroyed||this.iframe==null)return this.log("listSessions skipped — switcher unavailable"),[];try{const e=(await this.rpc({type:"list_sessions"})).sessions;return Array.isArray(e)?(this.log("listSessions resolved",{count:e.length}),e):(this.log("listSessions resolved with no sessions array"),[])}catch(i){return this.logError("listSessions failed — returning empty list",i),[]}}async switchTo(i,e){if(this.failed||this.destroyed||this.iframe==null){this.log("switchTo skipped — switcher unavailable",{sub:i});return}try{if(this.mode==="emit"){this.log("switchTo emit",{sub:i,listeners:this.switchListeners.length}),this.emitSwitch(i);return}const t=i==="__new__"?"login":"none",r=e?.returnTo??window.location.href;this.log("switchTo redirect",{sub:i,prompt:t,return_to:r}),await this.rpc({type:"redirect_authorize",login_hint:i,prompt:t,return_to:r})}catch(t){this.logError("switchTo failed",t)}}accountPageUrl(i){const e=`${this.origin}/account?login_hint=${encodeURIComponent(i)}`;return this.log("accountPageUrl",{sub:i,url:e}),e}destroy(){if(this.destroyed){this.log("destroy called again — no-op");return}this.destroyed=!0;try{window.removeEventListener("message",this.handleMessage);const i=new DOMException("DmonSwitcher destroyed","AbortError");this.log("destroy",{rejectingPending:this.pending.size}),this.pending.forEach(({reject:e})=>e(i)),this.pending.clear(),this.iframe?.remove(),this.resolveReady()}catch(i){this.logError("destroy encountered an error",i)}}on(i,e){i==="switch"?this.switchListeners.push(e):this.readyListeners.push(e)}log(i,e){this.debug&&(e===void 0?console.debug(`[DmonSwitcher] ${i}`):console.debug(`[DmonSwitcher] ${i}`,e))}logError(i,e){e===void 0?console.error(`[DmonSwitcher] ${i}`):console.error(`[DmonSwitcher] ${i}`,e)}emitSwitch(i){for(const e of this.switchListeners)try{e({sub:i})}catch(t){this.logError("switch handler threw",t)}}async rpc(i){if(this.destroyed||this.iframe==null)throw new DOMException("DmonSwitcher destroyed","AbortError");if(await this.readyPromise,this.destroyed||this.iframe==null)throw new DOMException("DmonSwitcher destroyed","AbortError");const e=String(this.nextRequestId++);this.log("rpc send",{request_id:e,...i});const t=this.iframe;return new Promise((r,o)=>{this.pending.set(e,{resolve:r,reject:o}),t.contentWindow?.postMessage({...i,request_id:e},this.origin)})}}exports.DmonSwitcher=l;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function d(s){if(typeof s!="object"||s===null)return!1;const r=s;return!(r.dmon_bridge!==!0||typeof r.type!="string")}function h(s){return typeof s.request_id=="string"}class a{constructor(r){this.iframe=null,this.nextRequestId=1,this.destroyed=!1,this.failed=!1,this.bridgeFailed=!1,this.readyReceived=!1,this.loadGraceTimer=null,this.pending=new Map,this.switchListeners=[],this.readyListeners=[],this.errorListeners=[],this.handleIframeLoad=()=>{this.log("iframe load event"),!(this.readyReceived||this.destroyed||this.failed||this.bridgeFailed)&&(this.loadGraceTimer=setTimeout(()=>{this.rejectBridge("DmonSwitcher: bridge iframe loaded but sent no ready message (CSP frame-ancestors block?)")},this.postLoadGraceMs))},this.handleIframeError=()=>{this.log("iframe error event"),this.rejectBridge("DmonSwitcher: bridge iframe failed to load (network error)")},this.handleMessage=e=>{if(this.iframe==null||!d(e.data))return;if(e.source!==this.iframe.contentWindow){this.log("message dropped: wrong source",{eventOrigin:e.origin,expectedOrigin:this.origin,hasSource:e.source!=null,sourceIsExpectedIframe:!1});return}if(e.origin!==this.origin){this.log("message dropped: wrong origin",{eventOrigin:e.origin,expectedOrigin:this.origin});return}const i=e.data;if(i.type==="ready"){this.log("ready received"),this.readyReceived=!0,this.loadGraceTimer!=null&&(clearTimeout(this.loadGraceTimer),this.loadGraceTimer=null),this.resolveReady();for(const o of this.readyListeners)try{o()}catch(n){this.logError("ready handler threw",n)}return}if(!h(i)){this.log("message dropped: no request_id");return}const t=this.pending.get(i.request_id);t!==void 0?(this.log("rpc reply",{request_id:i.request_id,type:i.type}),this.pending.delete(i.request_id),t.resolve(i)):this.log("rpc reply for unknown request_id — ignored",{request_id:i.request_id})},this.origin=r.dmonOrigin,this.mode=r.mode??"emit",this.debug=r.debug??!1,this.postLoadGraceMs=r.postLoadGraceMs??200,this.readyPromise=new Promise((e,i)=>{this.resolveReady=e,this.rejectReady=i});try{const e=`${r.dmonOrigin}/api/v1/authorize/${r.realmSlug}/embed/bridge?client_id=${encodeURIComponent(r.clientId)}`,i=document.createElement("iframe");i.setAttribute("aria-hidden","true"),i.setAttribute("sandbox","allow-scripts allow-same-origin"),i.style.display="none",i.src=e,document.body.appendChild(i),i.onload=this.handleIframeLoad,i.onerror=this.handleIframeError,this.iframe=i,window.addEventListener("message",this.handleMessage),this.log("constructed",{origin:this.origin,mode:this.mode,src:e})}catch(e){this.failed=!0,this.resolveReady(),this.logError("construction failed — switcher disabled",e)}}ready(){return this.readyPromise}async listSessions(){if(this.failed||this.destroyed||this.iframe==null)return this.log("listSessions skipped — switcher unavailable"),[];try{const e=(await this.rpc({type:"list_sessions"})).sessions;return Array.isArray(e)?(this.log("listSessions resolved",{count:e.length}),e):(this.log("listSessions resolved with no sessions array"),[])}catch{return[]}}async switchTo(r,e){if(this.failed||this.destroyed||this.iframe==null){this.log("switchTo skipped — switcher unavailable",{sub:r});return}try{if(this.mode==="emit"){this.log("switchTo emit",{sub:r,listeners:this.switchListeners.length}),this.emitSwitch(r);return}const i=r==="__new__"?"login":"none",t=e?.returnTo??window.location.href;this.log("switchTo redirect",{sub:r,prompt:i,return_to:t}),await this.rpc({type:"redirect_authorize",login_hint:r,prompt:i,return_to:t})}catch(i){this.logError("switchTo failed",i)}}accountPageUrl(r){const e=`${this.origin}/account?login_hint=${encodeURIComponent(r)}`;return this.log("accountPageUrl",{sub:r,url:e}),e}destroy(){if(this.destroyed){this.log("destroy called again — no-op");return}this.destroyed=!0;try{this.loadGraceTimer!=null&&(clearTimeout(this.loadGraceTimer),this.loadGraceTimer=null),window.removeEventListener("message",this.handleMessage);const r=new DOMException("DmonSwitcher destroyed","AbortError");this.log("destroy",{rejectingPending:this.pending.size}),this.pending.forEach(({reject:e})=>e(r)),this.pending.clear(),this.iframe?.remove(),this.resolveReady()}catch(r){this.logError("destroy encountered an error",r)}}on(r,e){r==="switch"?this.switchListeners.push(e):r==="ready"?this.readyListeners.push(e):this.errorListeners.push(e)}rejectBridge(r){if(this.bridgeFailed||this.destroyed||this.failed)return;this.bridgeFailed=!0;const e=new Error(r);this.log(`bridge failure: ${r}`),this.rejectReady(e),this.pending.forEach(({reject:i})=>{i(e)}),this.pending.clear();for(const i of this.errorListeners)try{i(e)}catch(t){this.logError("error handler threw",t)}}log(r,e){this.debug&&(e===void 0?console.debug(`[DmonSwitcher] ${r}`):console.debug(`[DmonSwitcher] ${r}`,e))}logError(r,e){e===void 0?console.error(`[DmonSwitcher] ${r}`):console.error(`[DmonSwitcher] ${r}`,e)}emitSwitch(r){for(const e of this.switchListeners)try{e({sub:r})}catch(i){this.logError("switch handler threw",i)}}async rpc(r){if(this.destroyed||this.iframe==null)throw new DOMException("DmonSwitcher destroyed","AbortError");if(await this.readyPromise,this.destroyed||this.iframe==null)throw new DOMException("DmonSwitcher destroyed","AbortError");const e=String(this.nextRequestId++);this.log("rpc send",{request_id:e,...r});const i=this.iframe;return new Promise((t,o)=>{this.pending.set(e,{resolve:t,reject:o}),i.contentWindow?.postMessage({...r,request_id:e},this.origin)})}}exports.DmonSwitcher=a;

package/dist/index.d.ts

@@ -17,11 +17,20 @@ export interface DmonSwitcherOptions {
      * Off by default.
      */
     debug?: boolean;
+    /**
+     * Grace period (ms) to wait for the bridge "ready" message after the iframe `load`
+     * event fires.  The iframe `load` event fires even when CSP `frame-ancestors` blocks
+     * rendering — the bridge JS never runs, so no handshake arrives.  After this window
+     * expires without a "ready" the promise is rejected.  Defaults to 200 ms.
+     * Set to 0 to reject synchronously on load (only safe in tests).
+     */
+    postLoadGraceMs?: number;
 }
 type SwitchHandler = (payload: {
     sub: string;
 }) => void;
 type ReadyHandler = () => void;
+type ErrorHandler = (err: Error) => void;
 export declare class DmonSwitcher {
     private readonly origin;
     private readonly mode;
@@ -29,12 +38,18 @@ export declare class DmonSwitcher {
     private readonly iframe;
     private readonly readyPromise;
     private resolveReady;
+    private rejectReady;
     private nextRequestId;
     private destroyed;
     private failed;
+    private bridgeFailed;
+    private readyReceived;
+    private loadGraceTimer;
+    private readonly postLoadGraceMs;
     private readonly pending;
     private readonly switchListeners;
     private readonly readyListeners;
+    private readonly errorListeners;
     constructor(opts: DmonSwitcherOptions);
     ready(): Promise<void>;
     listSessions(): Promise<Session[]>;
@@ -53,6 +68,10 @@ export declare class DmonSwitcher {
     destroy(): void;
     on(event: "switch", handler: SwitchHandler): void;
     on(event: "ready", handler: ReadyHandler): void;
+    on(event: "error", handler: ErrorHandler): void;
+    private rejectBridge;
+    private readonly handleIframeLoad;
+    private readonly handleIframeError;
     private log;
     private logError;
     private emitSwitch;

package/dist/index.js

@@ -1,15 +1,21 @@
-function h(s) {
+function d(s) {
   if (typeof s != "object" || s === null) return !1;
-  const i = s;
-  return !(i.dmon_bridge !== !0 || typeof i.type != "string");
+  const r = s;
+  return !(r.dmon_bridge !== !0 || typeof r.type != "string");
 }
-function d(s) {
+function h(s) {
   return typeof s.request_id == "string";
 }
-class l {
-  constructor(i) {
-    this.iframe = null, this.nextRequestId = 1, this.destroyed = !1, this.failed = !1, this.pending = /* @__PURE__ */ new Map(), this.switchListeners = [], this.readyListeners = [], this.handleMessage = (e) => {
-      if (this.iframe == null || !h(e.data)) return;
+class a {
+  constructor(r) {
+    this.iframe = null, this.nextRequestId = 1, this.destroyed = !1, this.failed = !1, this.bridgeFailed = !1, this.readyReceived = !1, this.loadGraceTimer = null, this.pending = /* @__PURE__ */ new Map(), this.switchListeners = [], this.readyListeners = [], this.errorListeners = [], this.handleIframeLoad = () => {
+      this.log("iframe load event"), !(this.readyReceived || this.destroyed || this.failed || this.bridgeFailed) && (this.loadGraceTimer = setTimeout(() => {
+        this.rejectBridge("DmonSwitcher: bridge iframe loaded but sent no ready message (CSP frame-ancestors block?)");
+      }, this.postLoadGraceMs));
+    }, this.handleIframeError = () => {
+      this.log("iframe error event"), this.rejectBridge("DmonSwitcher: bridge iframe failed to load (network error)");
+    }, this.handleMessage = (e) => {
+      if (this.iframe == null || !d(e.data)) return;
       if (e.source !== this.iframe.contentWindow) {
         this.log("message dropped: wrong source", {
           eventOrigin: e.origin,
@@ -23,9 +29,9 @@ class l {
         this.log("message dropped: wrong origin", { eventOrigin: e.origin, expectedOrigin: this.origin });
         return;
       }
-      const t = e.data;
-      if (t.type === "ready") {
-        this.log("ready received"), this.resolveReady();
+      const i = e.data;
+      if (i.type === "ready") {
+        this.log("ready received"), this.readyReceived = !0, this.loadGraceTimer != null && (clearTimeout(this.loadGraceTimer), this.loadGraceTimer = null), this.resolveReady();
         for (const o of this.readyListeners)
           try {
             o();
@@ -34,18 +40,18 @@ class l {
           }
         return;
       }
-      if (!d(t)) {
+      if (!h(i)) {
         this.log("message dropped: no request_id");
         return;
       }
-      const r = this.pending.get(t.request_id);
-      r !== void 0 ? (this.log("rpc reply", { request_id: t.request_id, type: t.type }), this.pending.delete(t.request_id), r.resolve(t)) : this.log("rpc reply for unknown request_id — ignored", { request_id: t.request_id });
-    }, this.origin = i.dmonOrigin, this.mode = i.mode ?? "emit", this.debug = i.debug ?? !1, this.readyPromise = new Promise((e) => {
-      this.resolveReady = e;
+      const t = this.pending.get(i.request_id);
+      t !== void 0 ? (this.log("rpc reply", { request_id: i.request_id, type: i.type }), this.pending.delete(i.request_id), t.resolve(i)) : this.log("rpc reply for unknown request_id — ignored", { request_id: i.request_id });
+    }, this.origin = r.dmonOrigin, this.mode = r.mode ?? "emit", this.debug = r.debug ?? !1, this.postLoadGraceMs = r.postLoadGraceMs ?? 200, this.readyPromise = new Promise((e, i) => {
+      this.resolveReady = e, this.rejectReady = i;
     });
     try {
-      const e = `${i.dmonOrigin}/api/v1/authorize/${i.realmSlug}/embed/bridge?client_id=${encodeURIComponent(i.clientId)}`, t = document.createElement("iframe");
-      t.setAttribute("aria-hidden", "true"), t.setAttribute("sandbox", "allow-scripts allow-same-origin"), t.style.display = "none", t.src = e, document.body.appendChild(t), this.iframe = t, window.addEventListener("message", this.handleMessage), this.log("constructed", { origin: this.origin, mode: this.mode, src: e });
+      const e = `${r.dmonOrigin}/api/v1/authorize/${r.realmSlug}/embed/bridge?client_id=${encodeURIComponent(r.clientId)}`, i = document.createElement("iframe");
+      i.setAttribute("aria-hidden", "true"), i.setAttribute("sandbox", "allow-scripts allow-same-origin"), i.style.display = "none", i.src = e, document.body.appendChild(i), i.onload = this.handleIframeLoad, i.onerror = this.handleIframeError, this.iframe = i, window.addEventListener("message", this.handleMessage), this.log("constructed", { origin: this.origin, mode: this.mode, src: e });
     } catch (e) {
       this.failed = !0, this.resolveReady(), this.logError("construction failed — switcher disabled", e);
     }
@@ -59,29 +65,29 @@ class l {
     try {
       const e = (await this.rpc({ type: "list_sessions" })).sessions;
       return Array.isArray(e) ? (this.log("listSessions resolved", { count: e.length }), e) : (this.log("listSessions resolved with no sessions array"), []);
-    } catch (i) {
-      return this.logError("listSessions failed — returning empty list", i), [];
+    } catch {
+      return [];
     }
   }
-  async switchTo(i, e) {
+  async switchTo(r, e) {
     if (this.failed || this.destroyed || this.iframe == null) {
-      this.log("switchTo skipped — switcher unavailable", { sub: i });
+      this.log("switchTo skipped — switcher unavailable", { sub: r });
       return;
     }
     try {
       if (this.mode === "emit") {
-        this.log("switchTo emit", { sub: i, listeners: this.switchListeners.length }), this.emitSwitch(i);
+        this.log("switchTo emit", { sub: r, listeners: this.switchListeners.length }), this.emitSwitch(r);
         return;
       }
-      const t = i === "__new__" ? "login" : "none", r = e?.returnTo ?? window.location.href;
-      this.log("switchTo redirect", { sub: i, prompt: t, return_to: r }), await this.rpc({
+      const i = r === "__new__" ? "login" : "none", t = e?.returnTo ?? window.location.href;
+      this.log("switchTo redirect", { sub: r, prompt: i, return_to: t }), await this.rpc({
         type: "redirect_authorize",
-        login_hint: i,
-        prompt: t,
-        return_to: r
+        login_hint: r,
+        prompt: i,
+        return_to: t
       });
-    } catch (t) {
-      this.logError("switchTo failed", t);
+    } catch (i) {
+      this.logError("switchTo failed", i);
     }
   }
   /**
@@ -92,9 +98,9 @@ class l {
    * so the user can choose how to open it (left click = same tab, middle/ctrl click =
    * new tab). Pure and side-effect free; safe to call at any time.
    */
-  accountPageUrl(i) {
-    const e = `${this.origin}/account?login_hint=${encodeURIComponent(i)}`;
-    return this.log("accountPageUrl", { sub: i, url: e }), e;
+  accountPageUrl(r) {
+    const e = `${this.origin}/account?login_hint=${encodeURIComponent(r)}`;
+    return this.log("accountPageUrl", { sub: r, url: e }), e;
   }
   destroy() {
     if (this.destroyed) {
@@ -103,47 +109,61 @@ class l {
     }
     this.destroyed = !0;
     try {
-      window.removeEventListener("message", this.handleMessage);
-      const i = new DOMException("DmonSwitcher destroyed", "AbortError");
-      this.log("destroy", { rejectingPending: this.pending.size }), this.pending.forEach(({ reject: e }) => e(i)), this.pending.clear(), this.iframe?.remove(), this.resolveReady();
-    } catch (i) {
-      this.logError("destroy encountered an error", i);
+      this.loadGraceTimer != null && (clearTimeout(this.loadGraceTimer), this.loadGraceTimer = null), window.removeEventListener("message", this.handleMessage);
+      const r = new DOMException("DmonSwitcher destroyed", "AbortError");
+      this.log("destroy", { rejectingPending: this.pending.size }), this.pending.forEach(({ reject: e }) => e(r)), this.pending.clear(), this.iframe?.remove(), this.resolveReady();
+    } catch (r) {
+      this.logError("destroy encountered an error", r);
     }
   }
-  on(i, e) {
-    i === "switch" ? this.switchListeners.push(e) : this.readyListeners.push(e);
+  on(r, e) {
+    r === "switch" ? this.switchListeners.push(e) : r === "ready" ? this.readyListeners.push(e) : this.errorListeners.push(e);
+  }
+  rejectBridge(r) {
+    if (this.bridgeFailed || this.destroyed || this.failed) return;
+    this.bridgeFailed = !0;
+    const e = new Error(r);
+    this.log(`bridge failure: ${r}`), this.rejectReady(e), this.pending.forEach(({ reject: i }) => {
+      i(e);
+    }), this.pending.clear();
+    for (const i of this.errorListeners)
+      try {
+        i(e);
+      } catch (t) {
+        this.logError("error handler threw", t);
+      }
   }
-  log(i, e) {
-    this.debug && (e === void 0 ? console.debug(`[DmonSwitcher] ${i}`) : console.debug(`[DmonSwitcher] ${i}`, e));
+  log(r, e) {
+    this.debug && (e === void 0 ? console.debug(`[DmonSwitcher] ${r}`) : console.debug(`[DmonSwitcher] ${r}`, e));
   }
   // Errors are always surfaced (not gated by `debug`) but never thrown — the library
   // must not crash the consuming application.
-  logError(i, e) {
-    e === void 0 ? console.error(`[DmonSwitcher] ${i}`) : console.error(`[DmonSwitcher] ${i}`, e);
+  logError(r, e) {
+    e === void 0 ? console.error(`[DmonSwitcher] ${r}`) : console.error(`[DmonSwitcher] ${r}`, e);
   }
   // Invoke each consumer "switch" handler in isolation: a throwing handler is logged and
   // skipped, never allowed to break the loop or propagate out of the library.
-  emitSwitch(i) {
+  emitSwitch(r) {
     for (const e of this.switchListeners)
       try {
-        e({ sub: i });
-      } catch (t) {
-        this.logError("switch handler threw", t);
+        e({ sub: r });
+      } catch (i) {
+        this.logError("switch handler threw", i);
       }
   }
-  async rpc(i) {
+  async rpc(r) {
     if (this.destroyed || this.iframe == null)
       throw new DOMException("DmonSwitcher destroyed", "AbortError");
     if (await this.readyPromise, this.destroyed || this.iframe == null)
       throw new DOMException("DmonSwitcher destroyed", "AbortError");
     const e = String(this.nextRequestId++);
-    this.log("rpc send", { request_id: e, ...i });
-    const t = this.iframe;
-    return new Promise((r, o) => {
-      this.pending.set(e, { resolve: r, reject: o }), t.contentWindow?.postMessage({ ...i, request_id: e }, this.origin);
+    this.log("rpc send", { request_id: e, ...r });
+    const i = this.iframe;
+    return new Promise((t, o) => {
+      this.pending.set(e, { resolve: t, reject: o }), i.contentWindow?.postMessage({ ...r, request_id: e }, this.origin);
     });
   }
 }
 export {
-  l as DmonSwitcher
+  a as DmonSwitcher
 };

package/package.json

@@ -1,6 +1,8 @@
 {
     "name": "@gcm-cz/dmon-switcher",
-    "version": "0.1.0",
+    "version": "1.0.2",
+    "repository": "gitlab:gcm-cz/dmon",
+    "license": "MIT",
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",
@@ -12,7 +14,10 @@
             "require": "./dist/index.cjs"
         }
     },
-    "files": ["dist"],
+    "files": [
+        "dist",
+        "README.md"
+    ],
     "scripts": {
         "build": "vite build && tsc --emitDeclarationOnly",
         "prepare": "vite build && tsc --emitDeclarationOnly",