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

package/dist/KycService.d.cts

@@ -0,0 +1,307 @@
+import { BaseDataService } from "@metamask/base-data-service";
+import type { DataServiceCacheUpdatedEvent, DataServiceGranularCacheUpdatedEvent, DataServiceInvalidateQueriesAction } from "@metamask/base-data-service";
+import type { CreateServicePolicyOptions } from "@metamask/controller-utils";
+import type { GeolocationControllerGetGeolocationAction } from "@metamask/geolocation-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { AuthenticationControllerGetBearerTokenAction } from "@metamask/profile-sync-controller/auth";
+import type { Infer, Struct } from "@metamask/superstruct";
+import type { QueryClientConfig } from "@tanstack/query-core";
+import type { KycServiceMethodActions } from "./KycService-method-action-types.cjs";
+import type { KycDisclaimer, KycSessionStatus } from "./types.cjs";
+import type { UkycStorageAccessToken } from "./ukyc/storageAccessToken.cjs";
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+export declare const serviceName = "KycService";
+/**
+ * Invalidates cached queries serviced by {@link KycService}.
+ */
+export type KycServiceInvalidateQueriesAction = DataServiceInvalidateQueriesAction<typeof serviceName>;
+/**
+ * Actions that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceActions = KycServiceMethodActions | KycServiceInvalidateQueriesAction;
+/**
+ * Actions from other messengers that {@link KycService} calls.
+ */
+type AllowedActions = AuthenticationControllerGetBearerTokenAction | GeolocationControllerGetGeolocationAction;
+/**
+ * Published when {@link KycService}'s cache is updated.
+ */
+export type KycServiceCacheUpdatedEvent = DataServiceCacheUpdatedEvent<typeof serviceName>;
+/**
+ * Published when a single key within {@link KycService}'s cache is updated.
+ */
+export type KycServiceGranularCacheUpdatedEvent = DataServiceGranularCacheUpdatedEvent<typeof serviceName>;
+/**
+ * Events that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceEvents = KycServiceCacheUpdatedEvent | KycServiceGranularCacheUpdatedEvent;
+/**
+ * Events from other messengers that {@link KycService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link KycService}.
+ */
+export type KycServiceMessenger = Messenger<typeof serviceName, KycServiceActions | AllowedActions, KycServiceEvents | AllowedEvents>;
+/**
+ * Options for constructing a {@link KycService}.
+ */
+export type KycServiceOptions = {
+    messenger: KycServiceMessenger;
+    fetch: typeof fetch;
+    /**
+     * Mandatory value that sets the base url to KYC api
+     */
+    baseUrl: string;
+    /**
+     * Base URL of the Fractal encryption service, from which the JWKS used to
+     * verify the `jwtChain` returned by {@link KycService.getWrappingKey} is
+     * fetched. Required to run the wrapping-key exchange in
+     * {@link KycService.fetchJwks}.
+     */
+    fractalEncryptionBaseUrl?: string;
+    /**
+     * Shared configuration applied to all queries exposed by the service (e.g. a
+     * default `staleTime`/`cacheTime`). Each data service gets its own
+     * `QueryClient`.
+     */
+    queryClientConfig?: QueryClientConfig;
+    policyOptions?: CreateServicePolicyOptions;
+};
+declare const CreateSessionResponseStruct: Struct<{
+    sessionToken: string;
+}, {
+    sessionToken: Struct<string, null>;
+}>;
+declare const WrappingKeyResponseStruct: Struct<{
+    id: string;
+    jwtChain: string;
+    sessionServerPublicKey: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+}, {
+    id: Struct<string, null>;
+    jwtChain: Struct<string, null>;
+    sessionServerPublicKey: Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+    }, {
+        kty: Struct<string, null>;
+        crv: Struct<string, null>;
+        x: Struct<string, null>;
+    }>;
+}>;
+export type WrappingKeyResponse = Infer<typeof WrappingKeyResponseStruct>;
+declare const JwksResponseStruct: Struct<{
+    keys: {
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }[];
+}, {
+    keys: Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }[], Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }, {
+        kty: Struct<string, null>;
+        crv: Struct<string, null>;
+        x: Struct<string, null>;
+        kid: Struct<string, null>;
+    }>>;
+}>;
+export type JwksResponse = Infer<typeof JwksResponseStruct>;
+declare const UkycSessionResponseStruct: Struct<{
+    sessionId: string;
+    kycStatus?: string | undefined;
+    finalStatus?: string | undefined;
+}, {
+    sessionId: Struct<string, null>;
+    kycStatus: Struct<string | undefined, null>;
+    finalStatus: Struct<string | undefined, null>;
+}>;
+export type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;
+declare const ApplicantAccessTokenResponseStruct: Struct<{
+    status: string;
+    applicantAccessToken: string;
+}, {
+    status: Struct<string, null>;
+    applicantAccessToken: Struct<string, null>;
+}>;
+export type ApplicantAccessTokenResponse = Infer<typeof ApplicantAccessTokenResponseStruct>;
+export type CreateSessionParams = {
+    email: string;
+    termsAcceptedAt: string;
+    disclaimerIds: string[];
+};
+export type CheckKycRequiredParams = {
+    accessToken: string;
+    country: string;
+    capabilities?: {
+        product: string;
+    }[];
+};
+export type GetWrappingKeyParams = {
+    sessionClientPublicKey: string;
+};
+/**
+ * The wrapped `data_encryption_key` sent to the UKYC backend when creating a
+ * session. `encryptedKey` and `nonce` are produced by `wrapEncryptionKey`;
+ * `sessionId` is the wrapping key id returned by `getWrappingKey`.
+ */
+export type WrappedEncryptionKey = {
+    sessionId: string;
+    encryptedKey: string;
+    nonce: string;
+};
+export type CreateUkycSessionParams = {
+    jwtToken: string;
+    vendorMetadata: Record<string, unknown>;
+    wrappedEncryptionKey: WrappedEncryptionKey;
+    /**
+     * The client-signed `ukyc_capability_token` (envelope: payload + Ed25519
+     * signature) authorizing later storage access for this session. It is minted
+     * by the client with `read`-only scope — see the UKYC storage-and-auth spec
+     * for how it is formed. Only the client holds the signing key, so only the
+     * client can mint it. The envelope is base64url-encoded into a compact string
+     * before it is sent to the backend.
+     */
+    ukycCapabilityToken: UkycStorageAccessToken;
+};
+export type GetSessionStatusParams = {
+    sessionId: string;
+};
+/**
+ * `KycService` communicates with the Universal KYC (UKYC) backend to drive the
+ * identity + document-verification flow. It is stateless and platform-agnostic:
+ * HTTP is performed through an injected `fetch`, and the auth bearer token and
+ * geolocation come from other controllers via the messenger.
+ *
+ * It extends {@link BaseDataService}, so every request is routed through
+ * `fetchQuery`: it is wrapped in the shared service policy (retries, circuit
+ * breaker) and its result is exposed via the service's `QueryClient`. Read-only
+ * endpoints (`fetchDisclaimers`, `fetchJwks`) are cached with a `staleTime`;
+ * the session-creating and status-polling endpoints opt out of caching
+ * (`staleTime`/`cacheTime` of `0`) so they never serve a stale result.
+ */
+export declare class KycService extends BaseDataService<typeof serviceName, KycServiceMessenger> {
+    #private;
+    /**
+     * Constructs a new KycService.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.fetch - A function used to make HTTP requests.
+     * @param options.baseUrl - Base URL of the KYC API
+     * @param options.fractalEncryptionBaseUrl - Base URL of the Fractal
+     * encryption service, from which the JWKS used to verify the wrapping-key
+     * `jwtChain` is fetched.
+     * @param options.queryClientConfig - Shared configuration for all queries
+     * exposed by the service.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, baseUrl, fractalEncryptionBaseUrl, queryClientConfig, policyOptions, }: KycServiceOptions);
+    /**
+     * Resolves the customer's country from the geolocation source and converts it
+     * to an ISO 3166-1 alpha-3 code.
+     *
+     * @returns The alpha-3 country code.
+     * @throws If the country cannot be determined or mapped.
+     */
+    getGeoCountry(): Promise<string>;
+    /**
+     * Fetches the disclaimers the customer must accept before a session is
+     * created.
+     *
+     * @param params - The parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code.
+     * @returns The disclaimers.
+     */
+    fetchDisclaimers({ country, }: {
+        country: string;
+    }): Promise<KycDisclaimer[]>;
+    /**
+     * Creates a vendor session via the UKYC backend.
+     *
+     * @param params - The session parameters.
+     * @returns The created session token.
+     */
+    createSession(params: CreateSessionParams): Promise<Infer<typeof CreateSessionResponseStruct>>;
+    /**
+     * Checks whether KYC is required for the given access token, country, and
+     * capabilities.
+     *
+     * @param params - The check parameters.
+     * @returns Whether KYC is required.
+     */
+    checkKycRequired(params: CheckKycRequiredParams): Promise<{
+        kycRequired: boolean;
+    }>;
+    /**
+     * Requests a per-session wrapping key from the UKYC backend.
+     *
+     * The client sends its ephemeral X25519 public key; the backend responds with
+     * its session public key (`sessionServerPublicKey`) and a `jwtChain` that
+     * attests it. The caller must verify `jwtChain` against the Fractal JWKS
+     * (see {@link KycService.fetchJwks}) before trusting the key to wrap the
+     * `data_encryption_key`.
+     *
+     * @param params - The parameters.
+     * @param params.sessionClientPublicKey - Our ephemeral X25519 public key
+     * (base64url).
+     * @returns The wrapping key id, `jwtChain`, and session server public key.
+     */
+    getWrappingKey(params: GetWrappingKeyParams): Promise<WrappingKeyResponse>;
+    /**
+     * Fetches the Fractal encryption service JWKS used to verify the `jwtChain`
+     * returned by {@link KycService.getWrappingKey}.
+     *
+     * This is an unauthenticated request to a well-known path on the Fractal
+     * host, distinct from the UKYC base URL.
+     *
+     * @returns The JWKS keys.
+     */
+    fetchJwks(): Promise<JwksResponse>;
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow,
+     * handing over the wrapped `data_encryption_key` and the client-signed,
+     * read-only `ukyc_capability_token` that authorizes later storage access for
+     * the session.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers.
+     */
+    createUkycSession(params: CreateUkycSessionParams): Promise<UkycSessionResponse>;
+    /**
+     * Creates (or refreshes) the SumSub verification journey for a UKYC session,
+     * returning the applicant access token used to launch the SDK.
+     *
+     * @param sessionId - The UKYC session id from `createUkycSession`.
+     * @returns The applicant access token and status.
+     */
+    createJourney(sessionId: string): Promise<ApplicantAccessTokenResponse>;
+    /**
+     * Fetches the current status of a UKYC session. Polled after the SumSub SDK
+     * completes to determine the final verification decision.
+     *
+     * @param params - The parameters.
+     * @param params.sessionId - The UKYC session id.
+     * @returns The session status.
+     */
+    getSessionStatus(params: GetSessionStatusParams): Promise<KycSessionStatus>;
+}
+export {};
+//# sourceMappingURL=KycService.d.cts.map

package/dist/KycService.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycService.d.cts","sourceRoot":"","sources":["../src/KycService.ts"],"names":[],"mappings":"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"}

package/dist/KycService.d.mts

@@ -0,0 +1,307 @@
+import { BaseDataService } from "@metamask/base-data-service";
+import type { DataServiceCacheUpdatedEvent, DataServiceGranularCacheUpdatedEvent, DataServiceInvalidateQueriesAction } from "@metamask/base-data-service";
+import type { CreateServicePolicyOptions } from "@metamask/controller-utils";
+import type { GeolocationControllerGetGeolocationAction } from "@metamask/geolocation-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { AuthenticationControllerGetBearerTokenAction } from "@metamask/profile-sync-controller/auth";
+import type { Infer, Struct } from "@metamask/superstruct";
+import type { QueryClientConfig } from "@tanstack/query-core";
+import type { KycServiceMethodActions } from "./KycService-method-action-types.mjs";
+import type { KycDisclaimer, KycSessionStatus } from "./types.mjs";
+import type { UkycStorageAccessToken } from "./ukyc/storageAccessToken.mjs";
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+export declare const serviceName = "KycService";
+/**
+ * Invalidates cached queries serviced by {@link KycService}.
+ */
+export type KycServiceInvalidateQueriesAction = DataServiceInvalidateQueriesAction<typeof serviceName>;
+/**
+ * Actions that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceActions = KycServiceMethodActions | KycServiceInvalidateQueriesAction;
+/**
+ * Actions from other messengers that {@link KycService} calls.
+ */
+type AllowedActions = AuthenticationControllerGetBearerTokenAction | GeolocationControllerGetGeolocationAction;
+/**
+ * Published when {@link KycService}'s cache is updated.
+ */
+export type KycServiceCacheUpdatedEvent = DataServiceCacheUpdatedEvent<typeof serviceName>;
+/**
+ * Published when a single key within {@link KycService}'s cache is updated.
+ */
+export type KycServiceGranularCacheUpdatedEvent = DataServiceGranularCacheUpdatedEvent<typeof serviceName>;
+/**
+ * Events that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceEvents = KycServiceCacheUpdatedEvent | KycServiceGranularCacheUpdatedEvent;
+/**
+ * Events from other messengers that {@link KycService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link KycService}.
+ */
+export type KycServiceMessenger = Messenger<typeof serviceName, KycServiceActions | AllowedActions, KycServiceEvents | AllowedEvents>;
+/**
+ * Options for constructing a {@link KycService}.
+ */
+export type KycServiceOptions = {
+    messenger: KycServiceMessenger;
+    fetch: typeof fetch;
+    /**
+     * Mandatory value that sets the base url to KYC api
+     */
+    baseUrl: string;
+    /**
+     * Base URL of the Fractal encryption service, from which the JWKS used to
+     * verify the `jwtChain` returned by {@link KycService.getWrappingKey} is
+     * fetched. Required to run the wrapping-key exchange in
+     * {@link KycService.fetchJwks}.
+     */
+    fractalEncryptionBaseUrl?: string;
+    /**
+     * Shared configuration applied to all queries exposed by the service (e.g. a
+     * default `staleTime`/`cacheTime`). Each data service gets its own
+     * `QueryClient`.
+     */
+    queryClientConfig?: QueryClientConfig;
+    policyOptions?: CreateServicePolicyOptions;
+};
+declare const CreateSessionResponseStruct: Struct<{
+    sessionToken: string;
+}, {
+    sessionToken: Struct<string, null>;
+}>;
+declare const WrappingKeyResponseStruct: Struct<{
+    id: string;
+    jwtChain: string;
+    sessionServerPublicKey: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+}, {
+    id: Struct<string, null>;
+    jwtChain: Struct<string, null>;
+    sessionServerPublicKey: Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+    }, {
+        kty: Struct<string, null>;
+        crv: Struct<string, null>;
+        x: Struct<string, null>;
+    }>;
+}>;
+export type WrappingKeyResponse = Infer<typeof WrappingKeyResponseStruct>;
+declare const JwksResponseStruct: Struct<{
+    keys: {
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }[];
+}, {
+    keys: Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }[], Struct<{
+        kty: string;
+        crv: string;
+        x: string;
+        kid: string;
+    }, {
+        kty: Struct<string, null>;
+        crv: Struct<string, null>;
+        x: Struct<string, null>;
+        kid: Struct<string, null>;
+    }>>;
+}>;
+export type JwksResponse = Infer<typeof JwksResponseStruct>;
+declare const UkycSessionResponseStruct: Struct<{
+    sessionId: string;
+    kycStatus?: string | undefined;
+    finalStatus?: string | undefined;
+}, {
+    sessionId: Struct<string, null>;
+    kycStatus: Struct<string | undefined, null>;
+    finalStatus: Struct<string | undefined, null>;
+}>;
+export type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;
+declare const ApplicantAccessTokenResponseStruct: Struct<{
+    status: string;
+    applicantAccessToken: string;
+}, {
+    status: Struct<string, null>;
+    applicantAccessToken: Struct<string, null>;
+}>;
+export type ApplicantAccessTokenResponse = Infer<typeof ApplicantAccessTokenResponseStruct>;
+export type CreateSessionParams = {
+    email: string;
+    termsAcceptedAt: string;
+    disclaimerIds: string[];
+};
+export type CheckKycRequiredParams = {
+    accessToken: string;
+    country: string;
+    capabilities?: {
+        product: string;
+    }[];
+};
+export type GetWrappingKeyParams = {
+    sessionClientPublicKey: string;
+};
+/**
+ * The wrapped `data_encryption_key` sent to the UKYC backend when creating a
+ * session. `encryptedKey` and `nonce` are produced by `wrapEncryptionKey`;
+ * `sessionId` is the wrapping key id returned by `getWrappingKey`.
+ */
+export type WrappedEncryptionKey = {
+    sessionId: string;
+    encryptedKey: string;
+    nonce: string;
+};
+export type CreateUkycSessionParams = {
+    jwtToken: string;
+    vendorMetadata: Record<string, unknown>;
+    wrappedEncryptionKey: WrappedEncryptionKey;
+    /**
+     * The client-signed `ukyc_capability_token` (envelope: payload + Ed25519
+     * signature) authorizing later storage access for this session. It is minted
+     * by the client with `read`-only scope — see the UKYC storage-and-auth spec
+     * for how it is formed. Only the client holds the signing key, so only the
+     * client can mint it. The envelope is base64url-encoded into a compact string
+     * before it is sent to the backend.
+     */
+    ukycCapabilityToken: UkycStorageAccessToken;
+};
+export type GetSessionStatusParams = {
+    sessionId: string;
+};
+/**
+ * `KycService` communicates with the Universal KYC (UKYC) backend to drive the
+ * identity + document-verification flow. It is stateless and platform-agnostic:
+ * HTTP is performed through an injected `fetch`, and the auth bearer token and
+ * geolocation come from other controllers via the messenger.
+ *
+ * It extends {@link BaseDataService}, so every request is routed through
+ * `fetchQuery`: it is wrapped in the shared service policy (retries, circuit
+ * breaker) and its result is exposed via the service's `QueryClient`. Read-only
+ * endpoints (`fetchDisclaimers`, `fetchJwks`) are cached with a `staleTime`;
+ * the session-creating and status-polling endpoints opt out of caching
+ * (`staleTime`/`cacheTime` of `0`) so they never serve a stale result.
+ */
+export declare class KycService extends BaseDataService<typeof serviceName, KycServiceMessenger> {
+    #private;
+    /**
+     * Constructs a new KycService.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.fetch - A function used to make HTTP requests.
+     * @param options.baseUrl - Base URL of the KYC API
+     * @param options.fractalEncryptionBaseUrl - Base URL of the Fractal
+     * encryption service, from which the JWKS used to verify the wrapping-key
+     * `jwtChain` is fetched.
+     * @param options.queryClientConfig - Shared configuration for all queries
+     * exposed by the service.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, baseUrl, fractalEncryptionBaseUrl, queryClientConfig, policyOptions, }: KycServiceOptions);
+    /**
+     * Resolves the customer's country from the geolocation source and converts it
+     * to an ISO 3166-1 alpha-3 code.
+     *
+     * @returns The alpha-3 country code.
+     * @throws If the country cannot be determined or mapped.
+     */
+    getGeoCountry(): Promise<string>;
+    /**
+     * Fetches the disclaimers the customer must accept before a session is
+     * created.
+     *
+     * @param params - The parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code.
+     * @returns The disclaimers.
+     */
+    fetchDisclaimers({ country, }: {
+        country: string;
+    }): Promise<KycDisclaimer[]>;
+    /**
+     * Creates a vendor session via the UKYC backend.
+     *
+     * @param params - The session parameters.
+     * @returns The created session token.
+     */
+    createSession(params: CreateSessionParams): Promise<Infer<typeof CreateSessionResponseStruct>>;
+    /**
+     * Checks whether KYC is required for the given access token, country, and
+     * capabilities.
+     *
+     * @param params - The check parameters.
+     * @returns Whether KYC is required.
+     */
+    checkKycRequired(params: CheckKycRequiredParams): Promise<{
+        kycRequired: boolean;
+    }>;
+    /**
+     * Requests a per-session wrapping key from the UKYC backend.
+     *
+     * The client sends its ephemeral X25519 public key; the backend responds with
+     * its session public key (`sessionServerPublicKey`) and a `jwtChain` that
+     * attests it. The caller must verify `jwtChain` against the Fractal JWKS
+     * (see {@link KycService.fetchJwks}) before trusting the key to wrap the
+     * `data_encryption_key`.
+     *
+     * @param params - The parameters.
+     * @param params.sessionClientPublicKey - Our ephemeral X25519 public key
+     * (base64url).
+     * @returns The wrapping key id, `jwtChain`, and session server public key.
+     */
+    getWrappingKey(params: GetWrappingKeyParams): Promise<WrappingKeyResponse>;
+    /**
+     * Fetches the Fractal encryption service JWKS used to verify the `jwtChain`
+     * returned by {@link KycService.getWrappingKey}.
+     *
+     * This is an unauthenticated request to a well-known path on the Fractal
+     * host, distinct from the UKYC base URL.
+     *
+     * @returns The JWKS keys.
+     */
+    fetchJwks(): Promise<JwksResponse>;
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow,
+     * handing over the wrapped `data_encryption_key` and the client-signed,
+     * read-only `ukyc_capability_token` that authorizes later storage access for
+     * the session.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers.
+     */
+    createUkycSession(params: CreateUkycSessionParams): Promise<UkycSessionResponse>;
+    /**
+     * Creates (or refreshes) the SumSub verification journey for a UKYC session,
+     * returning the applicant access token used to launch the SDK.
+     *
+     * @param sessionId - The UKYC session id from `createUkycSession`.
+     * @returns The applicant access token and status.
+     */
+    createJourney(sessionId: string): Promise<ApplicantAccessTokenResponse>;
+    /**
+     * Fetches the current status of a UKYC session. Polled after the SumSub SDK
+     * completes to determine the final verification decision.
+     *
+     * @param params - The parameters.
+     * @param params.sessionId - The UKYC session id.
+     * @returns The session status.
+     */
+    getSessionStatus(params: GetSessionStatusParams): Promise<KycSessionStatus>;
+}
+export {};
+//# sourceMappingURL=KycService.d.mts.map

package/dist/KycService.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycService.d.mts","sourceRoot":"","sources":["../src/KycService.ts"],"names":[],"mappings":"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"}