@mattrglobal/verifier-sdk-web 2.2.1-unstable.76 → 2.2.1-unstable.78

package/README.md

@@ -21,7 +21,7 @@
   - [Define wallet identifiers](#define-wallet-identifiers)
   - [Configure redirectUri](#configure-redirecturi)
   - [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state)
-  - [Run logic on session creation using onSessionCreate](#run-logic-on-session-creation-using-onsessioncreate)
+  - [React to presentation requests using onPresentationRequest](#react-to-presentation-requests-using-onpresentationrequest)
   - [Request credentials using the DC API](#request-credentials-using-the-dc-api)
 - [Request credentials examples](#request-credentials-examples)
   - [Request credentials with automatic flow selection](#request-credentials-with-automatic-flow-selection)
@@ -114,8 +114,8 @@ the following configurations and settings:
   same-device flows).
 - Optionally pass a `state` string to correlate the session with a record in your own system (see
   [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state)).
-- Optionally pass an `onSessionCreate` hook to run your own logic once the session has been created (see
-  [Run logic on session creation using onSessionCreate](#run-logic-on-session-creation-using-onsessioncreate)).
+- Optionally pass an `onPresentationRequest` hook to run your own logic each time a presentation request is issued (see
+  [React to presentation requests using onPresentationRequest](#react-to-presentation-requests-using-onpresentationrequest)).
 
 ## Initialize the SDK
 
@@ -341,15 +341,16 @@ MATTR VII platform and the SDK, see the
 [Correlating verification sessions with your system](https://learn.mattr.global/docs/verification/remote-web-verifiers/guides/correlating-verification-sessions)
 guide on MATTR Learn.
 
-## Run logic on session creation using `onSessionCreate`
+## React to presentation requests using `onPresentationRequest`
 
-`requestCredentials()` accepts an optional `onSessionCreate` hook that the SDK invokes immediately after the
-presentation session has been created on the MATTR VII verifier tenant, but before it continues with the rest of the
-presentation flow (rendering the QR code for cross-device flows or redirecting to the wallet for same-device flows). Use
-it to run your own logic against the freshly created session, for example persisting the `sessionId` in your backend,
-starting a timer, or emitting analytics.
+`requestCredentials()` accepts an optional `onPresentationRequest` hook that the SDK invokes once immediately after the
+presentation session has been created on the MATTR VII verifier tenant, and again every time the OpenID4VP auth-request
+URI is regenerated — for cross-device sessions this happens whenever the QR code shown in the iframe is refreshed.
+Same-device and Digital Credentials API sessions only ever invoke the hook once, since there is no refreshable request
+URI in those flows. Use it to run your own logic against the current request, for example mirroring the `authRequestUri`
+into your own system, starting a timer, or emitting analytics.
 
-The hook receives the session creation result and may be synchronous or asynchronous; the SDK awaits it before
+The hook receives the current presentation request and may be synchronous or asynchronous; the SDK awaits it before
 continuing:
 
 ```typescript
@@ -360,24 +361,46 @@ const options: MATTRVerifierSDK.RequestCredentialsOptions = {
     redirectUri: window.location.origin,
     walletProviderId,
   },
-  onSessionCreate: async (session) => {
-    // e.g. record the session against your own system before the flow continues
-    await fetch("/api/sessions", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ sessionId: session.sessionId }),
-    });
+  onPresentationRequest: async (request) => {
+    // e.g. record the current auth-request URI against your own system
+    if (request.type === "openid4vp") {
+      await fetch("/api/presentation-requests", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ sessionId: request.sessionId, authRequestUri: request.authRequestUri }),
+      });
+    }
   },
 };
 
 const results = await MATTRVerifierSDK.requestCredentials(options);
 ```
 
-- The hook is supported in both same-device and cross-device sessions.
-- The `session` argument exposes the identifiers for the created session, including its `sessionId`.
-- Any error thrown or promise rejection from the hook is intentionally ignored so it cannot disrupt the presentation
-  flow. If a step is critical, handle its errors inside the hook rather than relying on `requestCredentials()` to
-  surface them.
+- The hook fires once for same-device and Digital Credentials API sessions, and once immediately plus again on every QR
+  refresh for cross-device sessions.
+- The `request` argument is a discriminated union on `type`: for OpenID4VP sessions (`type: "openid4vp"`) it exposes
+  `sessionId` and `authRequestUri`; for Digital Credentials API sessions (`type: "digital-credentials-api"`) it exposes
+  only `sessionId`.
+- If the hook throws or its returned promise rejects on any firing, the in-progress presentation is aborted — the
+  session is aborted server-side and, for cross-device flows, the iframe is closed — and `requestCredentials()` resolves
+  with an `OnPresentationRequestFailed` error (see `RequestCredentialsErrorType`). This applies consistently whether the
+  failing firing was the initial one or a later cross-device refresh. If you want the presentation flow to continue
+  regardless of an error in the hook, catch and handle the error yourself inside the hook, for example:
+
+```typescript
+onPresentationRequest: async (request) => {
+  try {
+    await fetch("/api/presentation-requests", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+  } catch (error) {
+    // Swallow the error here so requestCredentials() continues with the presentation flow
+    console.error("Failed to record presentation request", error);
+  }
+},
+```
 
 ## Request credentials using the DC API
 
@@ -435,9 +458,9 @@ const result = await MATTRVerifierSDK.requestCredentials({
     walletProviderId, // Define the wallet identifier
     redirectUri, // Define the redirect URI (not required for cross-device only requests)
   },
-  onSessionCreate: (session) => {
-    // Optional: run your own logic once the session is created, before the flow continues
-    console.info("Session created", session.sessionId);
+  onPresentationRequest: (request) => {
+    // Optional: run your own logic each time a presentation request is issued
+    console.info("Presentation request", request.sessionId);
   },
 });
 
@@ -463,10 +486,11 @@ if (result.isErr()) {
   wallet-facing request URI and stored in session records. Returned in the response from `requestCredentials()`
   (cross-device) or `handleRedirectCallback()` (same-device). See
   [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state).
-- `onSessionCreate` (optional): A hook invoked with the session creation result once the presentation session has been
-  created, before the flow continues. Supported in both same-device and cross-device flows. Errors thrown by the hook
-  are ignored. See
-  [Run logic on session creation using onSessionCreate](#run-logic-on-session-creation-using-onsessioncreate).
+- `onPresentationRequest` (optional): A hook invoked once with the current presentation request after the session is
+  created, and again on every cross-device QR refresh. If the hook throws or rejects on any firing, the in-progress
+  presentation is aborted and `requestCredentials()` resolves with an `OnPresentationRequestFailed` error; catch and
+  handle errors inside the hook yourself if you want the flow to continue regardless. See
+  [React to presentation requests using onPresentationRequest](#react-to-presentation-requests-using-onpresentationrequest).
 - `mode`: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to
   `undefined` in the example for clarity).
 - `redirectUri`: Replace with a URI that matches one of the values in the

package/dist/lib/verifier-js-no-deps.cjs.js

@@ -7,7 +7,7 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2026-07-31
+ * Generated: 2026-08-02
  * Version: 2.2.0
  * Dependencies:
  */
@@ -221,6 +221,7 @@ const CreateSessionOpenId4vpResponseValidator = v__namespace.object({
     sessionId: v__namespace.string(),
     sessionKey: v__namespace.string(),
     sessionUrl: v__namespace.string(),
+    authRequestUri: v__namespace.string(),
     state: v__namespace.optional(v__namespace.string())
 });
 
@@ -262,6 +263,7 @@ var MessageEventDataType;
     MessageEventDataType["PresentationCompleted"] = "PresentationCompleted";
     MessageEventDataType["PresentationTimeout"] = "PresentationTimeout";
     MessageEventDataType["PresentationAbort"] = "PresentationAbort";
+    MessageEventDataType["PresentationRequestUpdated"] = "PresentationRequestUpdated";
 })(MessageEventDataType || (MessageEventDataType = {}));
 
 const OpenId4vpConfigSameDeviceOptionsValidator = v__namespace.object({
@@ -294,6 +296,7 @@ exports.RequestCredentialsErrorType = void 0;
     RequestCredentialsErrorType["RequestCredentialsFailed"] = "RequestCredentialsFailed";
     RequestCredentialsErrorType["Timeout"] = "Timeout";
     RequestCredentialsErrorType["Abort"] = "Abort";
+    RequestCredentialsErrorType["OnPresentationRequestFailed"] = "OnPresentationRequestFailed";
 })(exports.RequestCredentialsErrorType || (exports.RequestCredentialsErrorType = {}));
 
 var RequestCredentialsErrorMessage;
@@ -309,6 +312,7 @@ var RequestCredentialsErrorMessage;
     RequestCredentialsErrorMessage["Abort"] = "User aborted the session";
     RequestCredentialsErrorMessage["Timeout"] = "User session timeout";
     RequestCredentialsErrorMessage["StateMismatch"] = "State mismatch between requested session and back-channel result";
+    RequestCredentialsErrorMessage["OnPresentationRequestFailed"] = "The onPresentationRequest hook threw an error or rejected";
 })(RequestCredentialsErrorMessage || (RequestCredentialsErrorMessage = {}));
 
 exports.AbortSessionErrorType = void 0;
@@ -628,71 +632,111 @@ const closeCrossDeviceModal = options => {
     removeWindowMessageEventListener();
 };
 
-const receiveMessageHandler = options => async event => {
-    const {onComplete: onComplete, onFailure: onFailure, container: container, sessionId: sessionId, apiBaseUrl: apiBaseUrl, challenge: challenge, state: state} = options;
-    if (event.origin !== apiBaseUrl) {
-        return;
-    }
-    if (event.data.type === MessageEventDataType.PresentationCompleted && event.data.responseCode && event.data.sessionId) {
-        const responseCode = event.data.responseCode;
-        const result = await exchangeSessionResult({
-            challenge: challenge,
-            responseCode: responseCode,
-            sessionId: sessionId,
-            apiBaseUrl: apiBaseUrl
-        });
-        if (result.isErr()) {
+const receiveMessageHandler = options => {
+    let queue = Promise.resolve();
+    const processEvent = async event => {
+        const {onComplete: onComplete, onFailure: onFailure, container: container, sessionId: sessionId, sessionKey: sessionKey, apiBaseUrl: apiBaseUrl, challenge: challenge, state: state, onPresentationRequest: onPresentationRequest, isSettled: isSettled} = options;
+        if (isSettled() || event.origin !== apiBaseUrl) {
+            return;
+        }
+        if (event.data.type === MessageEventDataType.PresentationRequestUpdated && event.data.authRequestUri) {
+            if (onPresentationRequest) {
+                try {
+                    await onPresentationRequest({
+                        type: SessionType.Openid4vp,
+                        sessionId: sessionId,
+                        authRequestUri: event.data.authRequestUri
+                    });
+                } catch (cause) {
+                    if (isSettled()) {
+                        return;
+                    }
+                    onFailure({
+                        type: exports.RequestCredentialsErrorType.OnPresentationRequestFailed,
+                        message: RequestCredentialsErrorMessage.OnPresentationRequestFailed,
+                        cause: cause
+                    });
+                    closeCrossDeviceModal({
+                        container: container
+                    });
+                    await abortSession({
+                        apiBaseUrl: apiBaseUrl,
+                        sessionId: sessionId,
+                        sessionKey: sessionKey
+                    });
+                }
+            }
+            return;
+        }
+        if (event.data.type === MessageEventDataType.PresentationCompleted && event.data.responseCode && event.data.sessionId) {
+            const responseCode = event.data.responseCode;
+            const result = await exchangeSessionResult({
+                challenge: challenge,
+                responseCode: responseCode,
+                sessionId: sessionId,
+                apiBaseUrl: apiBaseUrl
+            });
+            if (isSettled()) {
+                return;
+            }
+            if (result.isErr()) {
+                onFailure({
+                    type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+                    message: RequestCredentialsErrorMessage.FailedToGetSessionResult
+                });
+                closeCrossDeviceModal({
+                    container: container
+                });
+                return;
+            }
+            const resultState = "challenge" in result.value ? result.value.state : undefined;
+            if (state !== undefined && resultState !== undefined && state !== resultState) {
+                onFailure({
+                    type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+                    message: RequestCredentialsErrorMessage.StateMismatch
+                });
+                closeCrossDeviceModal({
+                    container: container
+                });
+                return;
+            }
+            onComplete({
+                result: "challenge" in result.value ? result.value : undefined,
+                sessionId: result.value.sessionId,
+                sessionCompletedInRedirect: false,
+                state: resultState !== null && resultState !== void 0 ? resultState : state
+            });
+            closeCrossDeviceModal({
+                container: container
+            });
+            return;
+        }
+        if (event.data.type === MessageEventDataType.PresentationTimeout) {
             onFailure({
-                type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
-                message: RequestCredentialsErrorMessage.FailedToGetSessionResult
+                type: exports.RequestCredentialsErrorType.Timeout,
+                message: RequestCredentialsErrorMessage.Timeout
             });
             closeCrossDeviceModal({
                 container: container
             });
             return;
         }
-        const resultState = "challenge" in result.value ? result.value.state : undefined;
-        if (state !== undefined && resultState !== undefined && state !== resultState) {
+        if (event.data.type === MessageEventDataType.PresentationAbort) {
             onFailure({
-                type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
-                message: RequestCredentialsErrorMessage.StateMismatch
+                type: exports.RequestCredentialsErrorType.Abort,
+                message: RequestCredentialsErrorMessage.Abort
             });
             closeCrossDeviceModal({
                 container: container
             });
             return;
         }
-        onComplete({
-            result: "challenge" in result.value ? result.value : undefined,
-            sessionId: result.value.sessionId,
-            sessionCompletedInRedirect: false,
-            state: resultState !== null && resultState !== void 0 ? resultState : state
-        });
-        closeCrossDeviceModal({
-            container: container
-        });
-        return;
-    }
-    if (event.data.type === MessageEventDataType.PresentationTimeout) {
-        onFailure({
-            type: exports.RequestCredentialsErrorType.Timeout,
-            message: RequestCredentialsErrorMessage.Timeout
-        });
-        closeCrossDeviceModal({
-            container: container
-        });
-        return;
-    }
-    if (event.data.type === MessageEventDataType.PresentationAbort) {
-        onFailure({
-            type: exports.RequestCredentialsErrorType.Abort,
-            message: RequestCredentialsErrorMessage.Abort
-        });
-        closeCrossDeviceModal({
-            container: container
-        });
-        return;
-    }
+    };
+    return event => {
+        const next = queue.then((() => processEvent(event)));
+        queue = next.catch((() => undefined));
+        return next;
+    };
 };
 
 const openCrossDeviceModal = options => {
@@ -712,16 +756,18 @@ const openCrossDeviceModal = options => {
 };
 
 const requestCredentialsWithCrossDevice = async options => {
-    const {challenge: challenge, apiBaseUrl: apiBaseUrl, sessionUrl: sessionUrl, sessionId: sessionId, sessionKey: sessionKey, state: state} = options;
+    const {challenge: challenge, apiBaseUrl: apiBaseUrl, sessionUrl: sessionUrl, sessionId: sessionId, sessionKey: sessionKey, state: state, onPresentationRequest: onPresentationRequest} = options;
     const container = openCrossDeviceModal({
         sessionUrl: sessionUrl
     });
+    let settled = false;
     return await new Promise((resolve => {
         const abortController = setActiveSession({
             sessionId: sessionId,
             sessionKey: sessionKey
         });
         abortController.signal.addEventListener("abort", (() => {
+            settled = true;
             closeCrossDeviceModal({
                 container: container
             });
@@ -734,11 +780,20 @@ const requestCredentialsWithCrossDevice = async options => {
         listener = receiveMessageHandler({
             container: container,
             sessionId: sessionId,
+            sessionKey: sessionKey,
             apiBaseUrl: apiBaseUrl,
             challenge: challenge,
             state: state,
-            onComplete: data => resolve(neverthrow.ok(data)),
-            onFailure: error => resolve(neverthrow.err(error))
+            onPresentationRequest: onPresentationRequest,
+            isSettled: () => settled,
+            onComplete: data => {
+                settled = true;
+                resolve(neverthrow.ok(data));
+            },
+            onFailure: error => {
+                settled = true;
+                resolve(neverthrow.err(error));
+            }
         });
         window.addEventListener(WindowEventListenerType.message, listener, false);
     }));
@@ -986,7 +1041,7 @@ const requestCredentials = async options => {
     }
     assertType(RequestCredentialsOptionsValidator, "Invalid request credential options")(options);
     const {apiBaseUrl: apiBaseUrl, applicationId: applicationId} = initializeOptions;
-    const {challenge: challenge = generateChallenge(), credentialQuery: credentialQuery, openid4vpConfiguration: openid4vpConfiguration, state: state, onSessionCreate: onSessionCreate} = options;
+    const {challenge: challenge = generateChallenge(), credentialQuery: credentialQuery, openid4vpConfiguration: openid4vpConfiguration, state: state, onPresentationRequest: onPresentationRequest} = options;
     const dcApiSupported = isDigitalCredentialsApiSupported();
     const openId4VpRedirectUri = deriveOpenId4vpRedirectUri(openid4vpConfiguration);
     const createSessionResult = await createSession({
@@ -1008,10 +1063,29 @@ const requestCredentials = async options => {
     }
     const session = createSessionResult.value;
     const {sessionKey: sessionKey, sessionId: sessionId} = session;
-    if (onSessionCreate) {
+    if (onPresentationRequest) {
+        const presentationRequest = session.type === SessionType.DigitalCredentialsApi ? {
+            type: SessionType.DigitalCredentialsApi,
+            sessionId: sessionId
+        } : {
+            type: SessionType.Openid4vp,
+            sessionId: sessionId,
+            authRequestUri: session.authRequestUri
+        };
         try {
-            await onSessionCreate(session);
-        } catch (_b) {}
+            await onPresentationRequest(presentationRequest);
+        } catch (cause) {
+            await abortSession({
+                apiBaseUrl: apiBaseUrl,
+                sessionId: sessionId,
+                sessionKey: sessionKey
+            });
+            return neverthrow.err({
+                type: exports.RequestCredentialsErrorType.OnPresentationRequestFailed,
+                message: RequestCredentialsErrorMessage.OnPresentationRequestFailed,
+                cause: cause
+            });
+        }
     }
     if (session.type === SessionType.DigitalCredentialsApi) {
         const {request: request, sessionTtl: sessionTtl} = session;
@@ -1048,7 +1122,8 @@ const requestCredentials = async options => {
         sessionUrl: sessionUrl,
         sessionKey: sessionKey,
         sessionId: sessionId,
-        state: state
+        state: state,
+        onPresentationRequest: onPresentationRequest
     });
 };