@mattrglobal/verifier-sdk-web 2.2.1-unstable.9 → 2.3.0

package/README.md

@@ -21,6 +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)
+  - [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)
@@ -39,12 +40,10 @@ Request or download the
 ## Overview
 
 The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web
-applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/mdocs), supporting
-both [same-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#same-device-verification-workflow)
-and
-[cross-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#cross-device-verification-workflow)
-verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification
-processes.
+applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/concepts/mdocs),
+supporting both [same-device](https://learn.mattr.global/docs/verification/remote-overview#verification-flows) and
+[cross-device](https://learn.mattr.global/docs/verification/remote-overview#verification-flows) verification workflows.
+The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.
 
 ## Features
 
@@ -60,8 +59,8 @@ processes.
 
 ## How to get access to the MATTR Pi Verifier Web SDK
 
-Refer to our [SDK Docs landing page](https://learn.mattr.global/guides/get-started-pi) for step-by-step instructions to
-gain access to any of our SDKs.
+Refer to our [SDK Docs landing page](https://learn.mattr.global/docs/resources/get-started) for step-by-step
+instructions to gain access to any of our SDKs.
 
 > Please [reach out](mailto:dev-support@mattr.global) if you need any assistance.
 
@@ -115,6 +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 `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
 
@@ -126,9 +127,9 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 
 - `apiBaseUrl` (required): URL of the MATTR VII verifier tenant.
 - `applicationId` (required): Unique identifier of the verifier application. This must match the
-  [`id`](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!c=201&path=0/id&t=response)
-  parameter in the response returned when
-  [creating a Verifier application](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication)
+  [`id`](https://learn.mattr.global/docs/api-reference/platform/verifier-applications/postVerifierApplication) parameter
+  in the response returned when
+  [creating a Verifier application](https://learn.mattr.global/docs/api-reference/platform/verifier-applications/postVerifierApplication)
   on the MATTR VII verifier tenant.
 
 ## Prepare a credential query
@@ -227,13 +228,13 @@ This behavior can be explicitly overridden by specifying the desired mode in the
 
 You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier
 defined by the SDK in the credential request must match one of the identifiers of a
-[wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
-created on the MATTR VII verifier tenant.
+[wallet provider](https://learn.mattr.global/docs/api-reference/platform/wallet-providers/postWalletProvider) created on
+the MATTR VII verifier tenant.
 
 - If an identifier is provided and matches the `id` of one of the objects in the `walletProviders` array, the verifier
   tenant will invoke that specific wallet using its corresponding
-  [`authorizationEndpoint`](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=openid4vpConfiguration/authorizationEndpoint&t=request).
-- If an identifier is provided and does not match the `id` of any of the objects in the `walletProviders array`, the
+  [`authorizationEndpoint`](https://learn.mattr.global/docs/api-reference/platform/wallet-providers/postWalletProvider).
+- If an identifier is provided and does not match the `id` of any of the objects in the `walletProviders` array, the
   request will fail.
 - If an identifier is not provided, the verifier tenant will use `mdoc-openid4vp://` (default OID4VP scheme) to invoke
   any wallet.
@@ -243,7 +244,7 @@ created on the MATTR VII verifier tenant.
 When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete
 the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of
 the values defined in the
-[`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+[`redirectUris` array](https://learn.mattr.global/docs/api-reference/platform/verifier-applications/postVerifierApplication)
 when creating a verifier application.
 
 ## Correlate sessions with your own records using `state`
@@ -340,6 +341,67 @@ 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.
 
+## React to presentation requests using `onPresentationRequest`
+
+`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 current presentation request and may be synchronous or asynchronous; the SDK awaits it before
+continuing:
+
+```typescript
+const options: MATTRVerifierSDK.RequestCredentialsOptions = {
+  credentialQuery: [credentialQuery],
+  challenge: MATTRVerifierSDK.utils.generateChallenge(),
+  openid4vpConfiguration: {
+    redirectUri: window.location.origin,
+    walletProviderId,
+  },
+  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 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
 
 > DC API support is currently offered as a **tech preview**. As such, functionality may be limited, may not work in all
@@ -396,6 +458,10 @@ const result = await MATTRVerifierSDK.requestCredentials({
     walletProviderId, // Define the wallet identifier
     redirectUri, // Define the redirect URI (not required for cross-device only requests)
   },
+  onPresentationRequest: (request) => {
+    // Optional: run your own logic each time a presentation request is issued
+    console.info("Presentation request", request.sessionId);
+  },
 });
 
 if (result.isErr()) {
@@ -405,24 +471,30 @@ if (result.isErr()) {
 }
 ```
 
-- `apiBaseUrl` : Replace with the [`tenant_url`](https://learn.mattr.global/docs/platform-management/authentication) of
-  your MATTR VII verifier tenant.
+- `apiBaseUrl`: Replace with the
+  [`tenant_url`](https://learn.mattr.global/docs/platform-management/management-api/overview) of your MATTR VII verifier
+  tenant.
 - `credentialQuery`: The credential query to be used in the request.
 - `challenge`: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation
   session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge
   generated by your backend system.
 - `walletProviderId`: Replace with a wallet identifier that matches one of the identifiers of a
-  [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
-  created on the MATTR VII verifier tenant..
+  [wallet provider](https://learn.mattr.global/docs/api-reference/platform/wallet-providers/postWalletProvider) created
+  on the MATTR VII verifier tenant.
 - `state` (optional): Your own opaque correlation reference for this presentation session. Do not include personally
   identifiable information (PII), credentials, or anything sensitive, as the value is transmitted in plain text on the
   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).
+- `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
-  [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+- `redirectUri`: Replace with a URI that matches one of the values in the
+  [`redirectUris` array](https://learn.mattr.global/docs/api-reference/platform/verifier-applications/postVerifierApplication)
   in the MATTR VII tenant's verifier application.
 
 ## Request credentials with explicit same-device flow

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

@@ -7,8 +7,8 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2026-06-19
- * Version: 2.2.0
+ * Generated: 2026-08-17
+ * Version: 2.3.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())
 });
 
@@ -254,7 +255,7 @@ var LocalStorageKey;
 
 const MATTR_SDK_VERSION_HEADER = "x-mattr-sdk-version";
 
-const MATTR_SDK_VERSION_VALUE = "2.2.0";
+const MATTR_SDK_VERSION_VALUE = "2.3.0";
 
 var MessageEventDataType;
 
@@ -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;
@@ -579,7 +583,7 @@ const exchangeSessionResult = async ({challenge: challenge, responseCode: respon
         body: JSON.stringify(postData)
     });
     const responseResult = await withRetrySafeFetch(fetchResultFn, {
-        retries: 2,
+        retries: 4,
         retryHttpStatus: 404
     });
     if (responseResult.isErr()) {
@@ -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} = 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,6 +1063,30 @@ const requestCredentials = async options => {
     }
     const session = createSessionResult.value;
     const {sessionKey: sessionKey, sessionId: sessionId} = session;
+    if (onPresentationRequest) {
+        const presentationRequest = session.type === SessionType.DigitalCredentialsApi ? {
+            type: SessionType.DigitalCredentialsApi,
+            sessionId: sessionId
+        } : {
+            type: SessionType.Openid4vp,
+            sessionId: sessionId,
+            authRequestUri: session.authRequestUri
+        };
+        try {
+            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;
         return await requestCredentialsWithDigitalCredentialsApi({
@@ -1043,7 +1122,8 @@ const requestCredentials = async options => {
         sessionUrl: sessionUrl,
         sessionKey: sessionKey,
         sessionId: sessionId,
-        state: state
+        state: state,
+        onPresentationRequest: onPresentationRequest
     });
 };