@mattrglobal/verifier-sdk-web 2.2.1-unstable.6 → 2.2.1-unstable.61

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)
+  - [Run logic on session creation using onSessionCreate](#run-logic-on-session-creation-using-onsessioncreate)
   - [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 `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)).
 
 ## 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,44 @@ 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`
+
+`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.
+
+The hook receives the session creation result 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,
+  },
+  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 }),
+    });
+  },
+};
+
+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.
+
 ## 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 +435,10 @@ 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);
+  },
 });
 
 if (result.isErr()) {
@@ -405,24 +448,29 @@ 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).
+- `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).
 - `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,7 +7,7 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2026-06-15
+ * Generated: 2026-07-22
  * Version: 2.2.0
  * Dependencies:
  */
@@ -579,7 +579,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()) {
@@ -986,7 +986,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, onSessionCreate: onSessionCreate} = options;
     const dcApiSupported = isDigitalCredentialsApiSupported();
     const openId4VpRedirectUri = deriveOpenId4vpRedirectUri(openid4vpConfiguration);
     const createSessionResult = await createSession({
@@ -1008,6 +1008,11 @@ const requestCredentials = async options => {
     }
     const session = createSessionResult.value;
     const {sessionKey: sessionKey, sessionId: sessionId} = session;
+    if (onSessionCreate) {
+        try {
+            await onSessionCreate(session);
+        } catch (_b) {}
+    }
     if (session.type === SessionType.DigitalCredentialsApi) {
         const {request: request, sessionTtl: sessionTtl} = session;
         return await requestCredentialsWithDigitalCredentialsApi({