@metamask-previews/kyc-controller 0.0.0-preview-823dcff → 0.0.0-preview-e57e5c3dc

package/CHANGELOG.md

@@ -10,5 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Initial release of the `@metamask/kyc-controller` package for managing KYC / identity verification state across MetaMask clients ([#9781](https://github.com/MetaMask/core/pull/9781))
+- Add `KycController` and `KycService` for managing KYC / identity verification state across MetaMask clients  ([#9615](https://github.com/MetaMask/core/pull/9615))
+  - `KycController` (`BaseController`) owns the flow state machine, the Check/Auth frame message protocol, X25519 credential decryption, and SumSub orchestration via an injected `KycSumSubLauncher` adapter.
+  - `KycService` extends `BaseDataService` and performs the Universal KYC (UKYC) HTTP calls via an injected `fetch`, sourcing the auth bearer token and geolocation through the messenger.
+  - Exposes a vendor-neutral, per-product surface (`ramps`, `card`) plus reselect selectors.
+  - Add automatic post-authentication continuation to `KycController`
+  - Add optional `baseUrl` option to `KycService` constructor that overrides the base URL derived from `env`, enabling clients to target a custom (e.g. local or staging) KYC API
+  - Add UKYC session-status polling to `KycController`
+  - Add handling in `KycController.startSumSub` for applicants already being processed by the vendor
 
 [Unreleased]: https://github.com/MetaMask/core/

package/README.md

@@ -1,4 +1,4 @@
-# `@metamask/kyc-controller`
+# KYC Controller `@metamask/kyc-controller`
 
 Shared KYC / identity verification controller used across MetaMask clients
 
@@ -10,6 +10,14 @@ or
 
 `npm install @metamask/kyc-controller`
 
+## Development
+
+To rebuild the package automatically whenever you change a source file, run the `build:watch` script from core repository root folder:
+
+`yarn workspace @metamask/kyc-controller run build:watch`
+
+This watches `src/**/*.ts` and re-runs the build on each change (it also performs an initial build on start), which is useful when developing against a client that consumes this package locally.
+
 ## Contributing
 
-This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

package/dist/KycController-method-action-types.cjs

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=KycController-method-action-types.cjs.map

package/dist/KycController-method-action-types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycController-method-action-types.cjs","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { KycController } from './KycController.js';\n\n/**\n * Resolves persisted terms + geolocation, and auto-creates a session when\n * terms are already accepted and an email is available.\n *\n * @param params - Optional parameters.\n * @param params.email - The account email to associate with the session.\n * @param params.product - The consuming feature the flow runs for. When\n * provided, the controller automatically runs the KYC-required check once\n * authentication completes (and chains into document verification when KYC\n * is required). When omitted, the flow stops at `form` and the consumer must\n * call `checkKycRequired` manually.\n */\nexport type KycControllerInitializeAction = {\n  type: `KycController:initialize`;\n  handler: KycController['initialize'];\n};\n\n/**\n * Loads the disclaimers for the resolved (or provided) country.\n *\n * @param params - Optional parameters.\n * @param params.country - ISO 3166-1 alpha-3 country code override.\n */\nexport type KycControllerLoadDisclaimersAction = {\n  type: `KycController:loadDisclaimers`;\n  handler: KycController['loadDisclaimers'];\n};\n\n/**\n * Captures terms acceptance for the currently loaded disclaimers and creates\n * a session.\n *\n * @param params - Optional parameters.\n * @param params.email - The account email to associate with the session.\n * @param params.product - The consuming feature the flow runs for. See\n * {@link initialize} for how the product drives the automatic post\n * authentication continuation.\n */\nexport type KycControllerAcceptTermsAndStartSessionAction = {\n  type: `KycController:acceptTermsAndStartSession`;\n  handler: KycController['acceptTermsAndStartSession'];\n};\n\n/**\n * Clears the persisted terms acceptance.\n */\nexport type KycControllerClearSavedTermsAction = {\n  type: `KycController:clearSavedTerms`;\n  handler: KycController['clearSavedTerms'];\n};\n\n/**\n * Handles a message posted by a Check/Auth frame and advances the flow.\n *\n * The transport-agnostic caller (WebView on mobile, iframe on web) forwards\n * the raw message and injects the returned `reply` back into the frame.\n *\n * @param params - The parameters.\n * @param params.message - The raw message posted by the frame.\n * @returns An object whose optional `reply` should be posted back.\n */\nexport type KycControllerHandleFrameMessageAction = {\n  type: `KycController:handleFrameMessage`;\n  handler: KycController['handleFrameMessage'];\n};\n\n/**\n * Builds the Check-frame URL, or `null` when no session exists yet.\n *\n * @returns The Check-frame URL or `null`.\n */\nexport type KycControllerBuildCheckFrameUrlAction = {\n  type: `KycController:buildCheckFrameUrl`;\n  handler: KycController['buildCheckFrameUrl'];\n};\n\n/**\n * Builds the Auth-frame URL, or `null` when no client token is available.\n *\n * @returns The Auth-frame URL or `null`.\n */\nexport type KycControllerBuildAuthFrameUrlAction = {\n  type: `KycController:buildAuthFrameUrl`;\n  handler: KycController['buildAuthFrameUrl'];\n};\n\n/**\n * Builds the Reset-frame URL.\n *\n * @returns The Reset-frame URL.\n */\nexport type KycControllerBuildResetFrameUrlAction = {\n  type: `KycController:buildResetFrameUrl`;\n  handler: KycController['buildResetFrameUrl'];\n};\n\n/**\n * Checks whether KYC is required for a product and caches the result.\n *\n * @param params - The parameters.\n * @param params.product - The consuming feature.\n * @param params.country - Optional alpha-3 country override.\n * @returns Whether KYC is required.\n */\nexport type KycControllerCheckKycRequiredAction = {\n  type: `KycController:checkKycRequired`;\n  handler: KycController['checkKycRequired'];\n};\n\n/**\n * Reads the cached \"is KYC required\" result for a product.\n *\n * @param params - The parameters.\n * @param params.product - The consuming feature.\n * @returns The cached value, or `undefined` if not yet checked.\n */\nexport type KycControllerGetKycStatusAction = {\n  type: `KycController:getKycStatus`;\n  handler: KycController['getKycStatus'];\n};\n\n/**\n * Runs the SumSub document-verification sub-flow end to end:\n *\n * 1. requests a per-session wrapping key from the UKYC backend;\n * 2. verifies its `jwtChain` against the Fractal JWKS and confirms the\n * attested session server public key;\n * 3. derives the `data_encryption_key` from the wallet's UKYC\n * `local_user_secret` and wraps it for the session server;\n * 4. mints a client-signed, read-only `ukyc_capability_token` and creates\n * the UKYC session (handing over the wrapped key and the token);\n * 5. fetches the SumSub applicant access token; and\n * 6. presents the SDK via the injected launcher.\n *\n * If session creation reports the applicant is already approved on the relay\n * while the vendor is still finalizing (`kycStatus: approved`,\n * `finalStatus: pending`), the sub-flow stops at step 4 with a\n * `vendorProcessing` status and a message rather than launching the SDK.\n *\n * @param params - Optional parameters.\n * @param params.locale - BCP-47 locale for the SDK UI.\n * @param params.debug - Enables SDK debug logging.\n * @returns The SDK result.\n */\nexport type KycControllerStartSumSubAction = {\n  type: `KycController:startSumSub`;\n  handler: KycController['startSumSub'];\n};\n\n/**\n * Fetches the current UKYC session status for the active sub-flow and records\n * it on state. Useful for a one-off refresh outside the automatic polling\n * loop that {@link startSumSub} runs.\n *\n * @returns The fetched session status.\n * @throws If there is no active SumSub session to query.\n */\nexport type KycControllerGetSessionStatusAction = {\n  type: `KycController:getSessionStatus`;\n  handler: KycController['getSessionStatus'];\n};\n\n/**\n * Resets the flow to idle, clearing session tokens and sub-flow state while\n * preserving persisted terms acceptance and the per-product cache.\n */\nexport type KycControllerResetAction = {\n  type: `KycController:reset`;\n  handler: KycController['reset'];\n};\n\n/**\n * Union of all KycController action types.\n */\nexport type KycControllerMethodActions =\n  | KycControllerInitializeAction\n  | KycControllerLoadDisclaimersAction\n  | KycControllerAcceptTermsAndStartSessionAction\n  | KycControllerClearSavedTermsAction\n  | KycControllerHandleFrameMessageAction\n  | KycControllerBuildCheckFrameUrlAction\n  | KycControllerBuildAuthFrameUrlAction\n  | KycControllerBuildResetFrameUrlAction\n  | KycControllerCheckKycRequiredAction\n  | KycControllerGetKycStatusAction\n  | KycControllerStartSumSubAction\n  | KycControllerGetSessionStatusAction\n  | KycControllerResetAction;\n"]}

package/dist/KycController-method-action-types.d.cts

@@ -0,0 +1,168 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+import type { KycController } from "./KycController.cjs";
+/**
+ * Resolves persisted terms + geolocation, and auto-creates a session when
+ * terms are already accepted and an email is available.
+ *
+ * @param params - Optional parameters.
+ * @param params.email - The account email to associate with the session.
+ * @param params.product - The consuming feature the flow runs for. When
+ * provided, the controller automatically runs the KYC-required check once
+ * authentication completes (and chains into document verification when KYC
+ * is required). When omitted, the flow stops at `form` and the consumer must
+ * call `checkKycRequired` manually.
+ */
+export type KycControllerInitializeAction = {
+    type: `KycController:initialize`;
+    handler: KycController['initialize'];
+};
+/**
+ * Loads the disclaimers for the resolved (or provided) country.
+ *
+ * @param params - Optional parameters.
+ * @param params.country - ISO 3166-1 alpha-3 country code override.
+ */
+export type KycControllerLoadDisclaimersAction = {
+    type: `KycController:loadDisclaimers`;
+    handler: KycController['loadDisclaimers'];
+};
+/**
+ * Captures terms acceptance for the currently loaded disclaimers and creates
+ * a session.
+ *
+ * @param params - Optional parameters.
+ * @param params.email - The account email to associate with the session.
+ * @param params.product - The consuming feature the flow runs for. See
+ * {@link initialize} for how the product drives the automatic post
+ * authentication continuation.
+ */
+export type KycControllerAcceptTermsAndStartSessionAction = {
+    type: `KycController:acceptTermsAndStartSession`;
+    handler: KycController['acceptTermsAndStartSession'];
+};
+/**
+ * Clears the persisted terms acceptance.
+ */
+export type KycControllerClearSavedTermsAction = {
+    type: `KycController:clearSavedTerms`;
+    handler: KycController['clearSavedTerms'];
+};
+/**
+ * Handles a message posted by a Check/Auth frame and advances the flow.
+ *
+ * The transport-agnostic caller (WebView on mobile, iframe on web) forwards
+ * the raw message and injects the returned `reply` back into the frame.
+ *
+ * @param params - The parameters.
+ * @param params.message - The raw message posted by the frame.
+ * @returns An object whose optional `reply` should be posted back.
+ */
+export type KycControllerHandleFrameMessageAction = {
+    type: `KycController:handleFrameMessage`;
+    handler: KycController['handleFrameMessage'];
+};
+/**
+ * Builds the Check-frame URL, or `null` when no session exists yet.
+ *
+ * @returns The Check-frame URL or `null`.
+ */
+export type KycControllerBuildCheckFrameUrlAction = {
+    type: `KycController:buildCheckFrameUrl`;
+    handler: KycController['buildCheckFrameUrl'];
+};
+/**
+ * Builds the Auth-frame URL, or `null` when no client token is available.
+ *
+ * @returns The Auth-frame URL or `null`.
+ */
+export type KycControllerBuildAuthFrameUrlAction = {
+    type: `KycController:buildAuthFrameUrl`;
+    handler: KycController['buildAuthFrameUrl'];
+};
+/**
+ * Builds the Reset-frame URL.
+ *
+ * @returns The Reset-frame URL.
+ */
+export type KycControllerBuildResetFrameUrlAction = {
+    type: `KycController:buildResetFrameUrl`;
+    handler: KycController['buildResetFrameUrl'];
+};
+/**
+ * Checks whether KYC is required for a product and caches the result.
+ *
+ * @param params - The parameters.
+ * @param params.product - The consuming feature.
+ * @param params.country - Optional alpha-3 country override.
+ * @returns Whether KYC is required.
+ */
+export type KycControllerCheckKycRequiredAction = {
+    type: `KycController:checkKycRequired`;
+    handler: KycController['checkKycRequired'];
+};
+/**
+ * Reads the cached "is KYC required" result for a product.
+ *
+ * @param params - The parameters.
+ * @param params.product - The consuming feature.
+ * @returns The cached value, or `undefined` if not yet checked.
+ */
+export type KycControllerGetKycStatusAction = {
+    type: `KycController:getKycStatus`;
+    handler: KycController['getKycStatus'];
+};
+/**
+ * Runs the SumSub document-verification sub-flow end to end:
+ *
+ * 1. requests a per-session wrapping key from the UKYC backend;
+ * 2. verifies its `jwtChain` against the Fractal JWKS and confirms the
+ * attested session server public key;
+ * 3. derives the `data_encryption_key` from the wallet's UKYC
+ * `local_user_secret` and wraps it for the session server;
+ * 4. mints a client-signed, read-only `ukyc_capability_token` and creates
+ * the UKYC session (handing over the wrapped key and the token);
+ * 5. fetches the SumSub applicant access token; and
+ * 6. presents the SDK via the injected launcher.
+ *
+ * If session creation reports the applicant is already approved on the relay
+ * while the vendor is still finalizing (`kycStatus: approved`,
+ * `finalStatus: pending`), the sub-flow stops at step 4 with a
+ * `vendorProcessing` status and a message rather than launching the SDK.
+ *
+ * @param params - Optional parameters.
+ * @param params.locale - BCP-47 locale for the SDK UI.
+ * @param params.debug - Enables SDK debug logging.
+ * @returns The SDK result.
+ */
+export type KycControllerStartSumSubAction = {
+    type: `KycController:startSumSub`;
+    handler: KycController['startSumSub'];
+};
+/**
+ * Fetches the current UKYC session status for the active sub-flow and records
+ * it on state. Useful for a one-off refresh outside the automatic polling
+ * loop that {@link startSumSub} runs.
+ *
+ * @returns The fetched session status.
+ * @throws If there is no active SumSub session to query.
+ */
+export type KycControllerGetSessionStatusAction = {
+    type: `KycController:getSessionStatus`;
+    handler: KycController['getSessionStatus'];
+};
+/**
+ * Resets the flow to idle, clearing session tokens and sub-flow state while
+ * preserving persisted terms acceptance and the per-product cache.
+ */
+export type KycControllerResetAction = {
+    type: `KycController:reset`;
+    handler: KycController['reset'];
+};
+/**
+ * Union of all KycController action types.
+ */
+export type KycControllerMethodActions = KycControllerInitializeAction | KycControllerLoadDisclaimersAction | KycControllerAcceptTermsAndStartSessionAction | KycControllerClearSavedTermsAction | KycControllerHandleFrameMessageAction | KycControllerBuildCheckFrameUrlAction | KycControllerBuildAuthFrameUrlAction | KycControllerBuildResetFrameUrlAction | KycControllerCheckKycRequiredAction | KycControllerGetKycStatusAction | KycControllerStartSumSubAction | KycControllerGetSessionStatusAction | KycControllerResetAction;
+//# sourceMappingURL=KycController-method-action-types.d.cts.map

package/dist/KycController-method-action-types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycController-method-action-types.d.cts","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,4BAA2B;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,aAAa,CAAC,4BAA4B,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,IAAI,EAAE,iCAAiC,CAAC;IACxC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAC5C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,6BAA6B,GAC7B,kCAAkC,GAClC,6CAA6C,GAC7C,kCAAkC,GAClC,qCAAqC,GACrC,qCAAqC,GACrC,oCAAoC,GACpC,qCAAqC,GACrC,mCAAmC,GACnC,+BAA+B,GAC/B,8BAA8B,GAC9B,mCAAmC,GACnC,wBAAwB,CAAC"}

package/dist/KycController-method-action-types.d.mts

@@ -0,0 +1,168 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+import type { KycController } from "./KycController.mjs";
+/**
+ * Resolves persisted terms + geolocation, and auto-creates a session when
+ * terms are already accepted and an email is available.
+ *
+ * @param params - Optional parameters.
+ * @param params.email - The account email to associate with the session.
+ * @param params.product - The consuming feature the flow runs for. When
+ * provided, the controller automatically runs the KYC-required check once
+ * authentication completes (and chains into document verification when KYC
+ * is required). When omitted, the flow stops at `form` and the consumer must
+ * call `checkKycRequired` manually.
+ */
+export type KycControllerInitializeAction = {
+    type: `KycController:initialize`;
+    handler: KycController['initialize'];
+};
+/**
+ * Loads the disclaimers for the resolved (or provided) country.
+ *
+ * @param params - Optional parameters.
+ * @param params.country - ISO 3166-1 alpha-3 country code override.
+ */
+export type KycControllerLoadDisclaimersAction = {
+    type: `KycController:loadDisclaimers`;
+    handler: KycController['loadDisclaimers'];
+};
+/**
+ * Captures terms acceptance for the currently loaded disclaimers and creates
+ * a session.
+ *
+ * @param params - Optional parameters.
+ * @param params.email - The account email to associate with the session.
+ * @param params.product - The consuming feature the flow runs for. See
+ * {@link initialize} for how the product drives the automatic post
+ * authentication continuation.
+ */
+export type KycControllerAcceptTermsAndStartSessionAction = {
+    type: `KycController:acceptTermsAndStartSession`;
+    handler: KycController['acceptTermsAndStartSession'];
+};
+/**
+ * Clears the persisted terms acceptance.
+ */
+export type KycControllerClearSavedTermsAction = {
+    type: `KycController:clearSavedTerms`;
+    handler: KycController['clearSavedTerms'];
+};
+/**
+ * Handles a message posted by a Check/Auth frame and advances the flow.
+ *
+ * The transport-agnostic caller (WebView on mobile, iframe on web) forwards
+ * the raw message and injects the returned `reply` back into the frame.
+ *
+ * @param params - The parameters.
+ * @param params.message - The raw message posted by the frame.
+ * @returns An object whose optional `reply` should be posted back.
+ */
+export type KycControllerHandleFrameMessageAction = {
+    type: `KycController:handleFrameMessage`;
+    handler: KycController['handleFrameMessage'];
+};
+/**
+ * Builds the Check-frame URL, or `null` when no session exists yet.
+ *
+ * @returns The Check-frame URL or `null`.
+ */
+export type KycControllerBuildCheckFrameUrlAction = {
+    type: `KycController:buildCheckFrameUrl`;
+    handler: KycController['buildCheckFrameUrl'];
+};
+/**
+ * Builds the Auth-frame URL, or `null` when no client token is available.
+ *
+ * @returns The Auth-frame URL or `null`.
+ */
+export type KycControllerBuildAuthFrameUrlAction = {
+    type: `KycController:buildAuthFrameUrl`;
+    handler: KycController['buildAuthFrameUrl'];
+};
+/**
+ * Builds the Reset-frame URL.
+ *
+ * @returns The Reset-frame URL.
+ */
+export type KycControllerBuildResetFrameUrlAction = {
+    type: `KycController:buildResetFrameUrl`;
+    handler: KycController['buildResetFrameUrl'];
+};
+/**
+ * Checks whether KYC is required for a product and caches the result.
+ *
+ * @param params - The parameters.
+ * @param params.product - The consuming feature.
+ * @param params.country - Optional alpha-3 country override.
+ * @returns Whether KYC is required.
+ */
+export type KycControllerCheckKycRequiredAction = {
+    type: `KycController:checkKycRequired`;
+    handler: KycController['checkKycRequired'];
+};
+/**
+ * Reads the cached "is KYC required" result for a product.
+ *
+ * @param params - The parameters.
+ * @param params.product - The consuming feature.
+ * @returns The cached value, or `undefined` if not yet checked.
+ */
+export type KycControllerGetKycStatusAction = {
+    type: `KycController:getKycStatus`;
+    handler: KycController['getKycStatus'];
+};
+/**
+ * Runs the SumSub document-verification sub-flow end to end:
+ *
+ * 1. requests a per-session wrapping key from the UKYC backend;
+ * 2. verifies its `jwtChain` against the Fractal JWKS and confirms the
+ * attested session server public key;
+ * 3. derives the `data_encryption_key` from the wallet's UKYC
+ * `local_user_secret` and wraps it for the session server;
+ * 4. mints a client-signed, read-only `ukyc_capability_token` and creates
+ * the UKYC session (handing over the wrapped key and the token);
+ * 5. fetches the SumSub applicant access token; and
+ * 6. presents the SDK via the injected launcher.
+ *
+ * If session creation reports the applicant is already approved on the relay
+ * while the vendor is still finalizing (`kycStatus: approved`,
+ * `finalStatus: pending`), the sub-flow stops at step 4 with a
+ * `vendorProcessing` status and a message rather than launching the SDK.
+ *
+ * @param params - Optional parameters.
+ * @param params.locale - BCP-47 locale for the SDK UI.
+ * @param params.debug - Enables SDK debug logging.
+ * @returns The SDK result.
+ */
+export type KycControllerStartSumSubAction = {
+    type: `KycController:startSumSub`;
+    handler: KycController['startSumSub'];
+};
+/**
+ * Fetches the current UKYC session status for the active sub-flow and records
+ * it on state. Useful for a one-off refresh outside the automatic polling
+ * loop that {@link startSumSub} runs.
+ *
+ * @returns The fetched session status.
+ * @throws If there is no active SumSub session to query.
+ */
+export type KycControllerGetSessionStatusAction = {
+    type: `KycController:getSessionStatus`;
+    handler: KycController['getSessionStatus'];
+};
+/**
+ * Resets the flow to idle, clearing session tokens and sub-flow state while
+ * preserving persisted terms acceptance and the per-product cache.
+ */
+export type KycControllerResetAction = {
+    type: `KycController:reset`;
+    handler: KycController['reset'];
+};
+/**
+ * Union of all KycController action types.
+ */
+export type KycControllerMethodActions = KycControllerInitializeAction | KycControllerLoadDisclaimersAction | KycControllerAcceptTermsAndStartSessionAction | KycControllerClearSavedTermsAction | KycControllerHandleFrameMessageAction | KycControllerBuildCheckFrameUrlAction | KycControllerBuildAuthFrameUrlAction | KycControllerBuildResetFrameUrlAction | KycControllerCheckKycRequiredAction | KycControllerGetKycStatusAction | KycControllerStartSumSubAction | KycControllerGetSessionStatusAction | KycControllerResetAction;
+//# sourceMappingURL=KycController-method-action-types.d.mts.map

package/dist/KycController-method-action-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycController-method-action-types.d.mts","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,4BAA2B;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,aAAa,CAAC,4BAA4B,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,IAAI,EAAE,iCAAiC,CAAC;IACxC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,IAAI,EAAE,kCAAkC,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAC5C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,6BAA6B,GAC7B,kCAAkC,GAClC,6CAA6C,GAC7C,kCAAkC,GAClC,qCAAqC,GACrC,qCAAqC,GACrC,oCAAoC,GACpC,qCAAqC,GACrC,mCAAmC,GACnC,+BAA+B,GAC/B,8BAA8B,GAC9B,mCAAmC,GACnC,wBAAwB,CAAC"}

package/dist/KycController-method-action-types.mjs

@@ -0,0 +1,6 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+export {};
+//# sourceMappingURL=KycController-method-action-types.mjs.map

package/dist/KycController-method-action-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycController-method-action-types.mjs","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { KycController } from './KycController.js';\n\n/**\n * Resolves persisted terms + geolocation, and auto-creates a session when\n * terms are already accepted and an email is available.\n *\n * @param params - Optional parameters.\n * @param params.email - The account email to associate with the session.\n * @param params.product - The consuming feature the flow runs for. When\n * provided, the controller automatically runs the KYC-required check once\n * authentication completes (and chains into document verification when KYC\n * is required). When omitted, the flow stops at `form` and the consumer must\n * call `checkKycRequired` manually.\n */\nexport type KycControllerInitializeAction = {\n  type: `KycController:initialize`;\n  handler: KycController['initialize'];\n};\n\n/**\n * Loads the disclaimers for the resolved (or provided) country.\n *\n * @param params - Optional parameters.\n * @param params.country - ISO 3166-1 alpha-3 country code override.\n */\nexport type KycControllerLoadDisclaimersAction = {\n  type: `KycController:loadDisclaimers`;\n  handler: KycController['loadDisclaimers'];\n};\n\n/**\n * Captures terms acceptance for the currently loaded disclaimers and creates\n * a session.\n *\n * @param params - Optional parameters.\n * @param params.email - The account email to associate with the session.\n * @param params.product - The consuming feature the flow runs for. See\n * {@link initialize} for how the product drives the automatic post\n * authentication continuation.\n */\nexport type KycControllerAcceptTermsAndStartSessionAction = {\n  type: `KycController:acceptTermsAndStartSession`;\n  handler: KycController['acceptTermsAndStartSession'];\n};\n\n/**\n * Clears the persisted terms acceptance.\n */\nexport type KycControllerClearSavedTermsAction = {\n  type: `KycController:clearSavedTerms`;\n  handler: KycController['clearSavedTerms'];\n};\n\n/**\n * Handles a message posted by a Check/Auth frame and advances the flow.\n *\n * The transport-agnostic caller (WebView on mobile, iframe on web) forwards\n * the raw message and injects the returned `reply` back into the frame.\n *\n * @param params - The parameters.\n * @param params.message - The raw message posted by the frame.\n * @returns An object whose optional `reply` should be posted back.\n */\nexport type KycControllerHandleFrameMessageAction = {\n  type: `KycController:handleFrameMessage`;\n  handler: KycController['handleFrameMessage'];\n};\n\n/**\n * Builds the Check-frame URL, or `null` when no session exists yet.\n *\n * @returns The Check-frame URL or `null`.\n */\nexport type KycControllerBuildCheckFrameUrlAction = {\n  type: `KycController:buildCheckFrameUrl`;\n  handler: KycController['buildCheckFrameUrl'];\n};\n\n/**\n * Builds the Auth-frame URL, or `null` when no client token is available.\n *\n * @returns The Auth-frame URL or `null`.\n */\nexport type KycControllerBuildAuthFrameUrlAction = {\n  type: `KycController:buildAuthFrameUrl`;\n  handler: KycController['buildAuthFrameUrl'];\n};\n\n/**\n * Builds the Reset-frame URL.\n *\n * @returns The Reset-frame URL.\n */\nexport type KycControllerBuildResetFrameUrlAction = {\n  type: `KycController:buildResetFrameUrl`;\n  handler: KycController['buildResetFrameUrl'];\n};\n\n/**\n * Checks whether KYC is required for a product and caches the result.\n *\n * @param params - The parameters.\n * @param params.product - The consuming feature.\n * @param params.country - Optional alpha-3 country override.\n * @returns Whether KYC is required.\n */\nexport type KycControllerCheckKycRequiredAction = {\n  type: `KycController:checkKycRequired`;\n  handler: KycController['checkKycRequired'];\n};\n\n/**\n * Reads the cached \"is KYC required\" result for a product.\n *\n * @param params - The parameters.\n * @param params.product - The consuming feature.\n * @returns The cached value, or `undefined` if not yet checked.\n */\nexport type KycControllerGetKycStatusAction = {\n  type: `KycController:getKycStatus`;\n  handler: KycController['getKycStatus'];\n};\n\n/**\n * Runs the SumSub document-verification sub-flow end to end:\n *\n * 1. requests a per-session wrapping key from the UKYC backend;\n * 2. verifies its `jwtChain` against the Fractal JWKS and confirms the\n * attested session server public key;\n * 3. derives the `data_encryption_key` from the wallet's UKYC\n * `local_user_secret` and wraps it for the session server;\n * 4. mints a client-signed, read-only `ukyc_capability_token` and creates\n * the UKYC session (handing over the wrapped key and the token);\n * 5. fetches the SumSub applicant access token; and\n * 6. presents the SDK via the injected launcher.\n *\n * If session creation reports the applicant is already approved on the relay\n * while the vendor is still finalizing (`kycStatus: approved`,\n * `finalStatus: pending`), the sub-flow stops at step 4 with a\n * `vendorProcessing` status and a message rather than launching the SDK.\n *\n * @param params - Optional parameters.\n * @param params.locale - BCP-47 locale for the SDK UI.\n * @param params.debug - Enables SDK debug logging.\n * @returns The SDK result.\n */\nexport type KycControllerStartSumSubAction = {\n  type: `KycController:startSumSub`;\n  handler: KycController['startSumSub'];\n};\n\n/**\n * Fetches the current UKYC session status for the active sub-flow and records\n * it on state. Useful for a one-off refresh outside the automatic polling\n * loop that {@link startSumSub} runs.\n *\n * @returns The fetched session status.\n * @throws If there is no active SumSub session to query.\n */\nexport type KycControllerGetSessionStatusAction = {\n  type: `KycController:getSessionStatus`;\n  handler: KycController['getSessionStatus'];\n};\n\n/**\n * Resets the flow to idle, clearing session tokens and sub-flow state while\n * preserving persisted terms acceptance and the per-product cache.\n */\nexport type KycControllerResetAction = {\n  type: `KycController:reset`;\n  handler: KycController['reset'];\n};\n\n/**\n * Union of all KycController action types.\n */\nexport type KycControllerMethodActions =\n  | KycControllerInitializeAction\n  | KycControllerLoadDisclaimersAction\n  | KycControllerAcceptTermsAndStartSessionAction\n  | KycControllerClearSavedTermsAction\n  | KycControllerHandleFrameMessageAction\n  | KycControllerBuildCheckFrameUrlAction\n  | KycControllerBuildAuthFrameUrlAction\n  | KycControllerBuildResetFrameUrlAction\n  | KycControllerCheckKycRequiredAction\n  | KycControllerGetKycStatusAction\n  | KycControllerStartSumSubAction\n  | KycControllerGetSessionStatusAction\n  | KycControllerResetAction;\n"]}