@explorins/pers-signer 1.0.18 → 1.0.26

package/dist/index.d.ts

@@ -40,13 +40,9 @@ interface JWTLoginResponse {
         username: string;
         org_id: string;
     };
-    provider: string;
-}
-interface WrappedProviderResponse {
-    success: true;
-    data: unknown;
+    provider?: string;
 }
-type LoginResponse = JWTLoginResponse | WrappedProviderResponse;
+type LoginResponse = JWTLoginResponse;
 interface VerifyTokenRequest {
     token: string;
 }
@@ -67,69 +63,39 @@ interface VerifyTokenResponse {
     };
     tenantId: string;
 }
-interface InitRegistrationRequest {
-    authToken: string;
+interface SigningKey {
+    curve: string;
+    publicKey: string;
+    scheme: string;
 }
-interface InitRegistrationResponse {
-    success: true;
-    data: {
-        challenge?: string;
-        temporaryAuthenticationToken?: string;
-        user?: object;
-        [key: string]: unknown;
-    };
+interface Wallet {
+    address?: string;
+    chainId?: number;
+    custodial?: boolean;
+    dateCreated?: string;
+    externalId?: string;
+    id: string;
+    name?: string;
+    network?: string;
+    provider?: string;
+    signingKey?: SigningKey;
+    status?: string;
+    tags?: string[];
 }
-type CompleteRegistrationResponse = JWTLoginResponse | WrappedProviderResponse;
 interface ListWalletsRequest {
 }
 interface ListWalletsResponse {
     success: true;
     data: {
-        wallets?: Array<unknown>;
-        [key: string]: unknown;
+        items: Wallet[];
     };
 }
-interface InitSignatureRequest {
-    walletId: string;
-    request: unknown;
-}
-interface InitSignatureResponse {
-    success: true;
-    data: {
-        requestBody: unknown;
-        challenge: unknown;
-        [key: string]: unknown;
-    };
-}
-interface CompleteSignatureRequest {
-    walletId: string;
-    requestBody: unknown;
-    signedChallenge: unknown;
-}
 interface CompleteSignatureResponse {
     success: true;
     data: {
-        signature?: {
-            r: string;
-            s: string;
-            recid: number;
-            encoded: string;
-        } | string;
-        transaction?: unknown;
-        dateRequested?: string;
-        dateSigned?: string;
-        id?: string;
-        keyId?: string;
-        network?: string;
-        requestBody?: {
-            kind?: 'Eip712' | 'Hash' | string;
-            blockchainKind?: string;
-            [key: string]: unknown;
-        };
-        requester?: unknown;
-        status?: string;
-        walletId?: string;
-        [key: string]: unknown;
+        status: string;
+        challenge?: unknown;
+        signature?: number[];
     };
 }
 interface HealthCheckResponse {
@@ -139,9 +105,65 @@ interface HealthCheckResponse {
 /**
  * Types for WebAuthn provider abstraction
  */
+interface WebAuthnAssertion {
+    kind: 'Fido2';
+    credentialAssertion: {
+        credId: string;
+        clientData: string;
+        authenticatorData: string;
+        signature: string;
+        userHandle?: string;
+    };
+}
+interface WebAuthnAttestation {
+    id: string;
+    clientDataJSON: string;
+    attestationObject: string;
+}
+interface WebAuthnCredential {
+    id: string;
+    transports?: AuthenticatorTransport[];
+}
+interface WebAuthnSignChallenge {
+    challenge: string;
+    challengeIdentifier?: string;
+    allowCredentials?: {
+        webauthn?: WebAuthnCredential[];
+        key?: any[];
+    };
+    rpId?: string;
+    userVerification?: UserVerificationRequirement;
+    timeout?: number;
+    [key: string]: any;
+}
+interface WebAuthnCreateChallenge {
+    challenge: string;
+    user: {
+        id: string;
+        name: string;
+        displayName: string;
+    };
+    rp: {
+        id: string;
+        name: string;
+    };
+    pubKeyCredParams: {
+        type: "public-key";
+        alg: number;
+    }[];
+    authenticatorSelection?: AuthenticatorSelectionCriteria;
+    attestation?: AttestationConveyancePreference;
+    timeout?: number;
+    excludeCredentials?: {
+        id: string;
+        type: "public-key";
+        transports?: AuthenticatorTransport[];
+    }[];
+    [key: string]: any;
+}
 interface WebAuthnProvider {
-    create(challenge: any): Promise<any>;
-    sign(challenge: any): Promise<any>;
+    create(challenge: WebAuthnCreateChallenge): Promise<WebAuthnAttestation>;
+    sign(challenge: WebAuthnSignChallenge): Promise<WebAuthnAssertion>;
 }
 interface WebAuthnConfig {
     relyingParty: {
@@ -339,6 +361,15 @@ interface WalletItem {
     boundToEvmNetwork?: boolean;
     [key: string]: unknown;
 }
+interface GetWalletResponse {
+    id: string;
+    signingKey: {
+        publicKey: string;
+    };
+}
+type WalletMetadata = GetWalletResponse & {
+    boundToEvmNetwork: boolean;
+};
 
 /**
  * Error codes for transaction signing operations
@@ -366,6 +397,43 @@ interface TransactionSigningError extends Error {
     originalError?: unknown;
 }
 
+/**
+ * Signing status types for type-safe status updates
+ * Using const pattern instead of enum for better bundling compatibility
+ */
+declare const SigningStatus: {
+    readonly INITIALIZING: "initializing";
+    readonly AUTHENTICATING: "authenticating";
+    readonly PREPARING: "preparing";
+    readonly SIGNING: "signing";
+    readonly SUBMITTING: "submitting";
+    readonly COMPLETED: "completed";
+    readonly ERROR: "error";
+    readonly EXPIRED: "expired";
+};
+/**
+ * Type for signing status values
+ */
+type SigningStatus = typeof SigningStatus[keyof typeof SigningStatus];
+/**
+ * Status update data interface
+ */
+interface StatusUpdateData {
+    transactionId?: string;
+    transactionHash?: string;
+    error?: string;
+    [key: string]: any;
+}
+/**
+ * Status update callback interface for tracking transaction progress
+ *
+ * @interface StatusCallback
+ * @property {function} onStatusUpdate - Callback function that receives type-safe status updates
+ */
+interface StatusCallback {
+    onStatusUpdate?: (status: SigningStatus, message: string, data?: StatusUpdateData) => void;
+}
+
 /**
  * Central type definitions for the blockchain signer shared library
  * Single source of truth for all type exports
@@ -400,7 +468,7 @@ declare class WalletService {
      * @param signerToken - Signer JWT token
      * @returns Promise resolving to wallet data
      */
-    static listWallets(signerToken: string): Promise<unknown>;
+    static listWallets(signerToken: string): Promise<Wallet[]>;
 }
 
 /**
@@ -418,18 +486,12 @@ declare class PersService {
     private static tenantCache;
     private static currentProjectKey;
     private static currentTenantId;
-    private static useStaging;
     private static readonly TENANT_CACHE_TTL;
     /**
      * Configure the PERS API settings
      * @param config - The configuration object
      */
     static configure(config: Partial<PersApiConfig>): void;
-    /**
-     * Enable staging mode when project key is not available
-     * @param enableStaging Whether to use staging environment
-     */
-    static setStagingMode(enableStaging: boolean): void;
     /**
      * Get current configuration
      */
@@ -440,21 +502,21 @@ declare class PersService {
      * @param authToken - Optional auth token for authentication
      * @returns Promise with tenant public information
      */
-    static getTenantById(tenantId: string, authToken?: string): Promise<TenantPublicDTO>;
+    static getTenantById(tenantId: string, authToken: string): Promise<TenantPublicDTO>;
     /**
      * Initialize tenant configuration from JWT
      * @param tenantId - The tenant ID from JWT payload
      * @param authToken - Optional auth token for authentication
      * @returns Promise with tenant information
      */
-    static initializeTenant(tenantId: string, authToken?: string): Promise<TenantPublicDTO>;
+    static initializeTenant(tenantId: string, authToken: string): Promise<TenantPublicDTO>;
     /**
      * Ensure tenant is initialized and current, with automatic revalidation
      * @param tenantId - The tenant ID to ensure is initialized
      * @param authToken - Optional auth token for authentication
      * @returns Promise with tenant information
      */
-    static ensureTenantInitialized(tenantId: string, authToken?: string): Promise<TenantPublicDTO>;
+    static ensureTenantInitialized(tenantId: string, authToken: string): Promise<TenantPublicDTO>;
     /**
      * Get the current project key (either from tenant or fallback)
      * @param tenantId - Optional tenant ID to ensure is initialized
@@ -468,7 +530,7 @@ declare class PersService {
     /**
      * Authenticates a user with the PERS backend using their auth token
      *
-     * @param authToken - The authentication token received from DFNS after login/registration
+     * @param authToken - The authentication token received from backend after login/registration
      * @param tenantId - Optional tenant ID for automatic initialization
      * @returns A promise that resolves to the authentication response
      * @throws If the request fails
@@ -554,21 +616,11 @@ declare class SigningService {
     signBatch(authToken: string, walletId: string, requests: SigningRequest[]): Promise<CompleteSignatureResponse['data'][]>;
 }
 
-interface GetWalletResponse {
-    id: string;
-    signingKey: {
-        publicKey: string;
-    };
-}
-
 type WalletOptions = {
     wallet: WalletMetadata;
     authToken: string;
     signingService: SigningService;
 };
-type WalletMetadata = GetWalletResponse & {
-    boundToEvmNetwork: boolean;
-};
 declare class KeyWallet extends AbstractSigner {
     private options;
     private address?;
@@ -672,11 +724,9 @@ declare class TransactionErrorHandler {
         error?: {
             code?: string;
             message?: string;
-            developerMessage?: string;
         };
         code?: string;
         message?: string;
-        developerMessage?: string;
     }, transactionId: string): never;
     /**
      * Process PERS API errors and handle TRANSACTION_NOT_PENDING cases
@@ -873,12 +923,14 @@ declare function getHttpClient(): HttpClient;
  * @property {WebAuthnProvider} webAuthnProvider - WebAuthn provider for secure authentication
  * @property {string} [apiUrl] - Custom API base URL (defaults to production)
  * @property {string} [relyingPartyName] - WebAuthn relying party name for authentication
+ * @property {StatusCallback} [globalStatusCallback] - Optional global status callback for all operations
  */
 interface ExtendedPersSignerConfig {
     ethersProviderUrl?: string;
     webAuthnProvider: WebAuthnProvider;
     apiUrl?: string;
     relyingPartyName?: string;
+    globalStatusCallback?: StatusCallback;
 }
 interface PersSignerConfig extends Omit<ExtendedPersSignerConfig, 'webAuthnProvider'> {
 }
@@ -908,6 +960,11 @@ declare class PersSignerSDK {
      * @throws {Error} If required configuration is missing
      */
     constructor(config: ExtendedPersSignerConfig);
+    /**
+     * Helper method to trigger both global and method-specific status callbacks
+     * @private
+     */
+    private triggerStatusUpdate;
     /**
      * Authenticate user and cache session for 5 minutes
      *
@@ -915,20 +972,23 @@ declare class PersSignerSDK {
      * and caches the authenticated user session to avoid repeated authentication.
      *
      * @param {string} jwtToken - JWT token containing user identifier and tenant info
+     * @param {StatusCallback} [statusCallback] - Optional callback for status updates
      * @returns {Promise<AuthenticatedUser>} Authenticated user with access tokens
      * @throws {Error} If JWT is invalid, expired, or authentication fails
      *
      * @example
      * ```typescript
      * try {
-     *   const user = await sdk.loginUser(jwtToken);
+     *   const user = await sdk.loginUser(jwtToken, {
+     *     onStatusUpdate: (status, message) => console.log(`${status}: ${message}`)
+     *   });
      *   console.log('Authenticated:', user.identifier);
      * } catch (error) {
      *   console.error('Authentication failed:', error.message);
      * }
      * ```
      */
-    loginUser(jwtToken: string): Promise<AuthenticatedUser>;
+    loginUser(jwtToken: string, statusCallback?: StatusCallback): Promise<AuthenticatedUser>;
     /**
      * Sign a PERS transaction (legacy compatibility method)
      *
@@ -937,13 +997,16 @@ declare class PersSignerSDK {
      * maintained for backward compatibility.
      *
      * @param {string} jwtToken - JWT token containing transaction ID and user info
+     * @param {StatusCallback} [statusCallback] - Optional callback for status updates
      * @returns {Promise<TransactionSigningResult>} Signing result with signature and metadata
      * @throws {Error} If authentication fails, transaction ID missing, or signing fails
      *
      * @example
      * ```typescript
      * try {
-     *   const result = await sdk.signPersTransaction(jwtToken);
+     *   const result = await sdk.signPersTransaction(jwtToken, {
+     *     onStatusUpdate: (status, message) => console.log(`${status}: ${message}`)
+     *   });
      *   if (result.success) {
      *     console.log('Transaction signed:', result.signature);
      *   }
@@ -952,7 +1015,7 @@ declare class PersSignerSDK {
      * }
      * ```
      */
-    signPersTransaction(jwtToken: string): Promise<TransactionSigningResult>;
+    signPersTransaction(jwtToken: string, statusCallback?: StatusCallback): Promise<TransactionSigningResult>;
     /**
      * Sign a transaction with provided signing data
      *
@@ -961,17 +1024,20 @@ declare class PersSignerSDK {
      *
      * @param {CounterfactualWalletTransactionResponse | LegacyTransaction} signingData - Transaction data to sign
      * @param {string} jwtToken - JWT token containing transaction ID and user info
+     * @param {StatusCallback} [statusCallback] - Optional callback for status updates
      * @returns {Promise<TransactionSigningResult>} Signing result with signature and metadata
      * @throws {Error} If authentication fails, transaction ID missing, or signing fails
      *
      * @example
      * ```typescript
      * const signingData = await getTransactionData(transactionId);
-     * const result = await sdk.signTransaction(signingData, jwtToken);
+     * const result = await sdk.signTransaction(signingData, jwtToken, {
+     *   onStatusUpdate: (status, message) => console.log(`${status}: ${message}`)
+     * });
      * console.log('Signed transaction:', result.signature);
      * ```
      */
-    signTransaction(signingData: CounterfactualWalletTransactionResponse$1 | LegacyTransaction, jwtToken: string): Promise<TransactionSigningResult>;
+    signTransaction(signingData: CounterfactualWalletTransactionResponse$1 | LegacyTransaction, jwtToken: string, statusCallback?: StatusCallback): Promise<TransactionSigningResult>;
     /**
      * Complete transaction flow: sign and submit in one call
      *
@@ -980,13 +1046,18 @@ declare class PersSignerSDK {
      * transaction lifecycle automatically.
      *
      * @param {string} jwtToken - JWT token containing transaction ID and user info
+     * @param {StatusCallback} [statusCallback] - Optional callback for status updates
      * @returns {Promise<SubmissionResult>} Submission result with transaction hash and status
      * @throws {Error} If authentication, signing, or submission fails
      *
      * @example
      * ```typescript
      * try {
-     *   const result = await sdk.signAndSubmitPersTransaction(jwtToken);
+     *   const result = await sdk.signAndSubmitPersTransaction(jwtToken, {
+     *     onStatusUpdate: (status, message) => {
+     *       console.log(`Status: ${status} - ${message}`);
+     *     }
+     *   });
      *   if (result.success) {
      *     console.log('Transaction completed:', result.transactionHash);
      *     if (result.shouldRedirect) {
@@ -998,7 +1069,7 @@ declare class PersSignerSDK {
      * }
      * ```
      */
-    signAndSubmitPersTransaction(jwtToken: string): Promise<SubmissionResult>;
+    signAndSubmitPersTransaction(jwtToken: string, statusCallback?: StatusCallback): Promise<SubmissionResult>;
     /**
      * Submit a signed transaction to the blockchain
      *
@@ -1008,17 +1079,20 @@ declare class PersSignerSDK {
      *
      * @param {TransactionSigningResult} signingResult - Result from a successful transaction signing
      * @param {string} jwtToken - JWT token containing tenant and user info
+     * @param {StatusCallback} [statusCallback] - Optional callback for status updates
      * @returns {Promise<SubmissionResult>} Submission result with transaction hash and status
      * @throws {Error} If signing result is invalid, JWT is missing tenantId, or submission fails
      *
      * @example
      * ```typescript
      * const signedTx = await sdk.signPersTransaction(jwtToken);
-     * const result = await sdk.submitTransaction(signedTx, jwtToken);
+     * const result = await sdk.submitTransaction(signedTx, jwtToken, {
+     *   onStatusUpdate: (status, message) => console.log(`${status}: ${message}`)
+     * });
      * console.log('Transaction submitted:', result.transactionHash);
      * ```
      */
-    submitTransaction(signingResult: TransactionSigningResult, jwtToken: string): Promise<SubmissionResult>;
+    submitTransaction(signingResult: TransactionSigningResult, jwtToken: string, statusCallback?: StatusCallback): Promise<SubmissionResult>;
     /**
      * Clear user authentication cache
      *
@@ -1066,7 +1140,6 @@ declare function createPersSignerSDK(config: ExtendedPersSignerConfig): PersSign
  */
 declare class AuthenticationService {
     private signerToken;
-    private config;
     private webAuthnProvider;
     constructor(config: ExtendedPersSignerConfig);
     /**
@@ -1082,11 +1155,11 @@ declare class AuthenticationService {
      */
     verifyToken(token: string): Promise<VerifyTokenResponse>;
     /**
-     * Initialize user registration
-     * @param persToken - PERS JWT token (registration is public)
-     * @returns Promise resolving to registration challenge
+     * Register user with unified flow
+     * @param persToken - PERS JWT token
+     * @returns Promise resolving to authenticated user data
      */
-    initializeRegistration(persToken: string): Promise<unknown>;
+    registerUser(persToken: string): Promise<JWTLoginResponse>;
     /**
      * Get current signer token
      * @returns The current signer JWT token
@@ -1097,14 +1170,6 @@ declare class AuthenticationService {
      * @param token - Signer JWT token
      */
     setSignerToken(token: string): void;
-    /**
-     * Complete registration with WebAuthn challenge data (v1 API format)
-     * @param tmpAuthToken - Temporary auth token from init registration (temporaryAuthenticationToken)
-     * @param signedChallenge - WebAuthn credential response (will be restructured for backend)
-     * @param persToken - PERS JWT token (authToken)
-     * @returns Promise resolving to registration result
-     */
-    completeRegistrationWithChallenge(tmpAuthToken: string | null, signedChallenge: any, persToken: string): Promise<JWTLoginResponse | unknown>;
     /**
      * Combined authentication flow - handles both login and registration
      * @param identifier - User identifier (email/userId)
@@ -1129,7 +1194,8 @@ declare class HealthService {
 }
 
 /**
- * Browser-specific WebAuthn provider using DFNS browser SDK
+ * Browser-specific WebAuthn provider using native browser APIs
+ * Fully agnostic implementation without external SDK dependencies
  */
 
 /**
@@ -1138,7 +1204,8 @@ declare class HealthService {
 declare function getBrowserWebAuthnProvider(): Promise<WebAuthnProvider>;
 
 /**
- * React Native-specific WebAuthn provider using DFNS React Native SDK
+ * React Native-specific WebAuthn provider using react-native-passkey
+ * Fully agnostic implementation without external SDK dependencies
  * Falls back to browser implementation for React Native Web (Expo Web)
  */
 
@@ -1153,6 +1220,7 @@ declare function getReactNativeWebAuthnProvider(): Promise<WebAuthnProvider>;
  * Browser-compatible JWT handling without external dependencies
  */
 interface JWTPayload {
+    iss?: string;
     email?: string;
     identifierEmail?: string;
     userId?: string;
@@ -1225,5 +1293,5 @@ declare class UserCache {
     static cleanup(): number;
 }
 
-export { AuthenticationService, FetchHttpClient, HealthService, KeyWallet, PersService, PersSignerSDK, ReactNativeConfigProvider, SIGNABLE_STATUSES, SigningService, StaticConfigProvider, TransactionErrorHandler, TransactionSigningErrorCode, TransactionSigningService, TransactionSubmissionHandler, TransactionValidator, UserCache, WalletService, WebAuthnCoordinator, WebConfigProvider, createPersSignerSDK, extractJWTFromToken, getBrowserWebAuthnProvider, getConfigProvider, getHttpClient, getJWTPayload, getReactNativeWebAuthnProvider, getServiceConfig, isJWTExpired, setConfigProvider, setHttpClient };
-export type { AuthResponse, AuthenticatedUser, CombinedTransactionStatus, CompleteRegistrationResponse, CompleteSignatureRequest, CompleteSignatureResponse, ConfigProvider, HashSigningRequest, HealthCheckResponse, HttpClient, HttpRequestOptions, HttpResponse, InitRegistrationRequest, InitRegistrationResponse, InitSignatureRequest, InitSignatureResponse, JWTExtractionResult, JWTPayload, ListWalletsRequest, ListWalletsResponse, LoginRequest, LoginResponse, PersSignerConfig, RegistrationChallenge, RegistrationResult, RelyingPartyConfig, ServiceError, SignResponse, SignerApiError, SignerApiResponse, SigningAuthTokens, SigningChallenge, SigningRequest, SubmissionResult, TransactionSigningError, TransactionSigningParams, TransactionSigningResult, TransactionStatusInfo, TypedDataSigningRequest, UserCredentials, VerifyTokenRequest, VerifyTokenResponse, WalletItem, WalletListResponse, WebAuthnConfig, WebAuthnProvider };
+export { AuthenticationService, FetchHttpClient, HealthService, KeyWallet, PersService, PersSignerSDK, ReactNativeConfigProvider, SIGNABLE_STATUSES, SigningService, SigningStatus, StaticConfigProvider, TransactionErrorHandler, TransactionSigningErrorCode, TransactionSigningService, TransactionSubmissionHandler, TransactionValidator, UserCache, WalletService, WebAuthnCoordinator, WebConfigProvider, createPersSignerSDK, extractJWTFromToken, getBrowserWebAuthnProvider, getConfigProvider, getHttpClient, getJWTPayload, getReactNativeWebAuthnProvider, getServiceConfig, isJWTExpired, setConfigProvider, setHttpClient };
+export type { AuthResponse, AuthenticatedUser, CombinedTransactionStatus, CompleteSignatureResponse, ConfigProvider, HashSigningRequest, HealthCheckResponse, HttpClient, HttpRequestOptions, HttpResponse, JWTExtractionResult, JWTPayload, ListWalletsRequest, ListWalletsResponse, LoginRequest, LoginResponse, PersSignerConfig, RegistrationChallenge, RegistrationResult, RelyingPartyConfig, ServiceError, SignResponse, SignerApiError, SignerApiResponse, SigningAuthTokens, SigningChallenge, SigningRequest, StatusCallback, StatusUpdateData, SubmissionResult, TransactionSigningError, TransactionSigningParams, TransactionSigningResult, TransactionStatusInfo, TypedDataSigningRequest, UserCredentials, VerifyTokenRequest, VerifyTokenResponse, WalletItem, WalletListResponse, WebAuthnConfig, WebAuthnProvider };