@gcm-cz/dmon-switcher 1.2.1 → 1.3.1

package/README.md

@@ -51,15 +51,15 @@ const switcher = new DmonSwitcher({
 });
 
 // Register a switch handler before awaiting ready().
-switcher.on("switch", ({ sub }) => {
-    if (sub === "__new__") {
+switcher.on("switch", ({ loginHint }) => {
+    if (loginHint === "__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 }); });
+    performSilentAuth({ loginHint, prompt: "none" })
+        .catch(() => { window.location.href = buildAuthorizeUrl({ loginHint }); });
 });
 
 // Wait for the bridge to signal ready, then fetch the session list.
@@ -67,11 +67,12 @@ await switcher.ready();
 const sessions: Session[] = await switcher.listSessions();
 renderMyUserMenu(sessions);
 
-// Switch to a user when selected in your menu.
-await switcher.switchTo(selectedSub);
+// Switch to a user when selected in your menu. Pass `session.sub` (the user id); the
+// switcher resolves it to the login_hint (username) via the cached session list.
+await switcher.switchTo(selectedSession.sub);
 
 // Build the account-page URL for an anchor — the user decides how to open it.
-const accountHref = switcher.accountPageUrl(currentUserSub);
+const accountHref = switcher.accountPageUrl(currentSub);
 // <a href={accountHref}>Account settings</a>
 
 // Clean up when the component unmounts.
@@ -97,8 +98,8 @@ function UserMenu({ currentSub }: { currentSub: string }) {
         });
         switcherRef.current = switcher;
 
-        switcher.on("switch", ({ sub }) => {
-            // your re-auth logic
+        switcher.on("switch", ({ loginHint }) => {
+            // your re-auth logic — loginHint is the username (or "__new__")
         });
 
         switcher.ready()
@@ -133,8 +134,8 @@ function UserMenu({ currentSub }: { currentSub: string }) {
 
 ```typescript
 interface Session {
-    sub: string;          // Stable user identifier (OIDC "sub" claim)
-    name: string;         // Display name
+    sub: string;          // OIDC subject — the user id; pass to switchTo() / accountPageUrl()
+    name: string;         // Username — used by the switcher as the login_hint (resolved from sub)
     given_name?: string;
     family_name?: string;
     picture?: string;     // Profile picture URL
@@ -194,12 +195,15 @@ 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.
+Initiates a user switch. `sub` is the target account's `Session.sub` (the user id), or the
+`"__new__"` sentinel. The switcher resolves `sub` to the OIDC `login_hint` (the username,
+`Session.name`) via the most recent `listSessions()` result; unresolved values are passed
+through unchanged.
 
-- **`"emit"` mode** — fires all `switch` listeners with `{ sub }` and resolves immediately.
-  The RP is responsible for triggering OIDC re-authentication.
+- **`"emit"` mode** — fires all `switch` listeners with `{ loginHint }` (the resolved
+  username) 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
+  to the DMon `/authorize` endpoint with `login_hint=<resolved username>`, `prompt=none`, and
   `redirect_uri=opts.returnTo ?? window.location.href`.
 
 **`__new__` sentinel:** `switchTo("__new__")` uses `prompt=login` to force fresh credential
@@ -207,15 +211,16 @@ entry and append a new session to the cookie.
 
 #### `accountPageUrl(sub: string): string`
 
-Returns (does **not** open) the DMon account-page URL for `sub`:
+Returns (does **not** open) the DMon account-page URL for the given account's `Session.sub`
+(the user id), resolved to a `login_hint` (the username) via the cached `listSessions()` result:
 
 ```
-{dmonOrigin}/account?login_hint={encodeURIComponent(sub)}
+{dmonOrigin}/account?login_hint={encodeURIComponent(resolvedUsername)}
 ```
 
 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.
+contains a session for that user; otherwise it falls back to the standard login flow.
 
 #### `destroy(): void`
 
@@ -223,7 +228,7 @@ Removes the iframe, deregisters `window` message listeners, rejects all pending
 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`
+#### `on(event: "switch", handler: (payload: { loginHint: string }) => void): void`
 
 Registers a handler fired by `switchTo()` in `"emit"` mode.
 

package/dist/index.cjs

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

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 export interface Session {
+    /**
+     * OIDC subject identifier — the DMon user id as a string. Equals the `sub`
+     * claim of the access/ID tokens issued for this user, so relying parties can
+     * correlate a switcher account with its tokens.
+     */
     sub: string;
+    /**
+     * Username / login identifier. Pass this to {@link DmonSwitcher.switchTo} and
+     * {@link DmonSwitcher.accountPageUrl} as the OIDC `login_hint` when switching
+     * to this account.
+     */
     name: string;
     given_name?: string;
     family_name?: string;
@@ -27,7 +37,7 @@ export interface DmonSwitcherOptions {
     postLoadGraceMs?: number;
 }
 type SwitchHandler = (payload: {
-    sub: string;
+    loginHint: string;
 }) => void;
 type ReadyHandler = () => void;
 type ErrorHandler = (err: Error) => void;
@@ -50,21 +60,40 @@ export declare class DmonSwitcher {
     private readonly switchListeners;
     private readonly readyListeners;
     private readonly errorListeners;
+    /** Most recent listSessions() result, used to resolve a `sub` (user id) to its login_hint. */
+    private lastSessions;
     constructor(opts: DmonSwitcherOptions);
     ready(): Promise<void>;
     listSessions(): Promise<Session[]>;
+    /**
+     * Switch to a previously authenticated account.
+     *
+     * @param sub - The {@link Session.sub} of the target account (the user id), or the
+     *   `"__new__"` sentinel to force interactive login. The switcher resolves it to the
+     *   OIDC `login_hint` (username) via the cached {@link listSessions} result.
+     */
     switchTo(sub: string, opts?: {
         returnTo?: string;
     }): Promise<void>;
     /**
-     * Build the URL of the DMon account page for the given user, pre-filled with the
+     * Build the URL of the DMon account page for the given account, pre-filled with the
      * `login_hint` so DMon can mount it silently if that user's session is in the cookie.
      *
+     * @param sub - The {@link Session.sub} of the target account (the user id); resolved to
+     *   the OIDC `login_hint` (username) via the cached {@link listSessions} result.
+     *
      * This only constructs the string — it never navigates. Put it in an anchor's `href`
      * 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(sub: string): string;
+    /**
+     * Resolve a {@link Session.sub} (the user id) to the OIDC `login_hint` (the username)
+     * using the most recent {@link listSessions} result. The `"__new__"` sentinel is passed
+     * through unchanged. When no cached session matches (e.g. `listSessions` has not run
+     * yet), the input is returned unchanged as a best-effort fallback.
+     */
+    private resolveLoginHint;
     destroy(): void;
     on(event: "switch", handler: SwitchHandler): void;
     on(event: "ready", handler: ReadyHandler): void;

package/dist/index.js

@@ -1,36 +1,36 @@
-function d(s) {
+function h(s) {
   if (typeof s != "object" || s === null) return !1;
-  const r = s;
-  return !(r.dmon_bridge !== !0 || typeof r.type != "string");
+  const e = s;
+  return !(e.dmon_bridge !== !0 || typeof e.type != "string");
 }
-function h(s) {
+function d(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 = /* @__PURE__ */ new Map(), this.switchListeners = [], this.readyListeners = [], this.errorListeners = [], this.handleIframeLoad = () => {
+  constructor(e) {
+    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.lastSessions = [], 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.handleMessage = (i) => {
+      if (this.iframe == null || !h(i.data)) return;
+      if (i.source !== this.iframe.contentWindow) {
         this.log("message dropped: wrong source", {
-          eventOrigin: e.origin,
+          eventOrigin: i.origin,
           expectedOrigin: this.origin,
-          hasSource: e.source != null,
+          hasSource: i.source != null,
           sourceIsExpectedIframe: !1
         });
         return;
       }
-      if (e.origin !== this.origin) {
-        this.log("message dropped: wrong origin", { eventOrigin: e.origin, expectedOrigin: this.origin });
+      if (i.origin !== this.origin) {
+        this.log("message dropped: wrong origin", { eventOrigin: i.origin, expectedOrigin: this.origin });
         return;
       }
-      const i = e.data;
-      if (i.type === "ready") {
+      const r = i.data;
+      if (r.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 {
@@ -40,20 +40,20 @@ class a {
           }
         return;
       }
-      if (!h(i)) {
+      if (!d(r)) {
         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;
+      const t = this.pending.get(r.request_id);
+      t !== void 0 ? (this.log("rpc reply", { request_id: r.request_id, type: r.type }), this.pending.delete(r.request_id), t.resolve(r)) : this.log("rpc reply for unknown request_id — ignored", { request_id: r.request_id });
+    }, this.origin = e.dmonOrigin, this.mode = e.mode ?? "emit", this.debug = e.debug ?? !1, this.postLoadGraceMs = e.postLoadGraceMs ?? 200, this.readyPromise = new Promise((i, r) => {
+      this.resolveReady = i, this.rejectReady = r;
     });
     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);
+      const i = `${e.dmonOrigin}/api/v1/authorize/${e.realmSlug}/embed/bridge?client_id=${encodeURIComponent(e.clientId)}`, r = document.createElement("iframe");
+      r.setAttribute("aria-hidden", "true"), r.setAttribute("sandbox", "allow-scripts allow-same-origin"), r.style.display = "none", r.src = i, document.body.appendChild(r), r.onload = this.handleIframeLoad, r.onerror = this.handleIframeError, this.iframe = r, window.addEventListener("message", this.handleMessage), this.log("constructed", { origin: this.origin, mode: this.mode, src: i });
+    } catch (i) {
+      this.failed = !0, this.resolveReady(), this.logError("construction failed — switcher disabled", i);
     }
   }
   ready() {
@@ -63,44 +63,64 @@ class a {
     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"), []);
+      const i = (await this.rpc({ type: "list_sessions" })).sessions;
+      return Array.isArray(i) ? (this.log("listSessions resolved", { count: i.length }), this.lastSessions = i, this.lastSessions) : (this.log("listSessions resolved with no sessions array"), []);
     } catch {
       return [];
     }
   }
-  async switchTo(r, e) {
+  /**
+   * Switch to a previously authenticated account.
+   *
+   * @param sub - The {@link Session.sub} of the target account (the user id), or the
+   *   `"__new__"` sentinel to force interactive login. The switcher resolves it to the
+   *   OIDC `login_hint` (username) via the cached {@link listSessions} result.
+   */
+  async switchTo(e, i) {
     if (this.failed || this.destroyed || this.iframe == null) {
-      this.log("switchTo skipped — switcher unavailable", { sub: r });
+      this.log("switchTo skipped — switcher unavailable", { sub: e });
       return;
     }
     try {
+      const r = this.resolveLoginHint(e);
       if (this.mode === "emit") {
-        this.log("switchTo emit", { sub: r, listeners: this.switchListeners.length }), this.emitSwitch(r);
+        this.log("switchTo emit", { sub: e, loginHint: 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({
+      const t = e === "__new__" ? "login" : "none", o = i?.returnTo ?? window.location.href;
+      this.log("switchTo redirect", { sub: e, loginHint: r, prompt: t, return_to: o }), await this.rpc({
         type: "redirect_authorize",
         login_hint: r,
-        prompt: i,
-        return_to: t
+        prompt: t,
+        return_to: o
       });
-    } catch (i) {
-      this.logError("switchTo failed", i);
+    } catch (r) {
+      this.logError("switchTo failed", r);
     }
   }
   /**
-   * Build the URL of the DMon account page for the given user, pre-filled with the
+   * Build the URL of the DMon account page for the given account, pre-filled with the
    * `login_hint` so DMon can mount it silently if that user's session is in the cookie.
    *
+   * @param sub - The {@link Session.sub} of the target account (the user id); resolved to
+   *   the OIDC `login_hint` (username) via the cached {@link listSessions} result.
+   *
    * This only constructs the string — it never navigates. Put it in an anchor's `href`
    * 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(r) {
-    const e = `${this.origin}/account?login_hint=${encodeURIComponent(r)}`;
-    return this.log("accountPageUrl", { sub: r, url: e }), e;
+  accountPageUrl(e) {
+    const i = this.resolveLoginHint(e), r = `${this.origin}/account?login_hint=${encodeURIComponent(i)}`;
+    return this.log("accountPageUrl", { sub: e, loginHint: i, url: r }), r;
+  }
+  /**
+   * Resolve a {@link Session.sub} (the user id) to the OIDC `login_hint` (the username)
+   * using the most recent {@link listSessions} result. The `"__new__"` sentinel is passed
+   * through unchanged. When no cached session matches (e.g. `listSessions` has not run
+   * yet), the input is returned unchanged as a best-effort fallback.
+   */
+  resolveLoginHint(e) {
+    return e === "__new__" ? e : this.lastSessions.find((r) => r.sub === e)?.name ?? e;
   }
   destroy() {
     if (this.destroyed) {
@@ -110,57 +130,57 @@ class a {
     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);
+      const e = new DOMException("DmonSwitcher destroyed", "AbortError");
+      this.log("destroy", { rejectingPending: this.pending.size }), this.pending.forEach(({ reject: i }) => i(e)), this.pending.clear(), this.iframe?.remove(), this.resolveReady();
+    } catch (e) {
+      this.logError("destroy encountered an error", e);
     }
   }
-  on(r, e) {
-    r === "switch" ? this.switchListeners.push(e) : r === "ready" ? this.readyListeners.push(e) : this.errorListeners.push(e);
+  on(e, i) {
+    e === "switch" ? this.switchListeners.push(i) : e === "ready" ? this.readyListeners.push(i) : this.errorListeners.push(i);
   }
-  rejectBridge(r) {
+  rejectBridge(e) {
     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);
+    const i = new Error(e);
+    this.log(`bridge failure: ${e}`), this.rejectReady(i), this.pending.forEach(({ reject: r }) => {
+      r(i);
     }), this.pending.clear();
-    for (const i of this.errorListeners)
+    for (const r of this.errorListeners)
       try {
-        i(e);
+        r(i);
       } 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));
+  log(e, i) {
+    this.debug && (i === void 0 ? console.debug(`[DmonSwitcher] ${e}`) : console.debug(`[DmonSwitcher] ${e}`, i));
   }
   // Errors are always surfaced (not gated by `debug`) but never thrown — the library
   // must not crash the consuming application.
-  logError(r, e) {
-    e === void 0 ? console.error(`[DmonSwitcher] ${r}`) : console.error(`[DmonSwitcher] ${r}`, e);
+  logError(e, i) {
+    i === void 0 ? console.error(`[DmonSwitcher] ${e}`) : console.error(`[DmonSwitcher] ${e}`, i);
   }
   // 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(r) {
-    for (const e of this.switchListeners)
+  emitSwitch(e) {
+    for (const i of this.switchListeners)
       try {
-        e({ sub: r });
-      } catch (i) {
-        this.logError("switch handler threw", i);
+        i({ loginHint: e });
+      } catch (r) {
+        this.logError("switch handler threw", r);
       }
   }
-  async rpc(r) {
+  async rpc(e) {
     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;
+    const i = String(this.nextRequestId++);
+    this.log("rpc send", { request_id: i, ...e });
+    const r = this.iframe;
     return new Promise((t, o) => {
-      this.pending.set(e, { resolve: t, reject: o }), i.contentWindow?.postMessage({ ...r, request_id: e }, this.origin);
+      this.pending.set(i, { resolve: t, reject: o }), r.contentWindow?.postMessage({ ...e, request_id: i }, this.origin);
     });
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gcm-cz/dmon-switcher",
-    "version": "1.2.1",
+    "version": "1.3.1",
     "repository": "gitlab:gcm-cz/dmon",
     "license": "MIT",
     "type": "module",