@getpara/react-native-wallet 2.22.0 → 2.24.0

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export * from '@getpara/web-sdk';
 export { ParaMobile } from './react-native/ParaMobile.js';
+export { ParaPasskeyError, type ParaPasskeyErrorCode, PARA_PASSKEY_ERROR_CODES } from './react-native/errors.js';
 export type * from '@getpara/viem-v2-integration/aa';
 export * from './provider/index.js';
 export * from '@getpara/react-core';
+import type { ParaMobile as _ParaMobile } from './react-native/ParaMobile.js';
+/** Hook for retrieving the Para client from the provider context. */
+export declare const useClient: () => _ParaMobile | undefined;

package/dist/index.js

@@ -1,6 +1,10 @@
 export * from '@getpara/web-sdk';
 export { ParaMobile } from './react-native/ParaMobile.js';
+export { ParaPasskeyError, PARA_PASSKEY_ERROR_CODES } from './react-native/errors.js';
 // React Native provider (wraps ParaProviderCore with AsyncStorage persistence)
 export * from './provider/index.js';
 // Core provider hooks and config types — platform-agnostic, work with any ParaCore subclass
 export * from '@getpara/react-core';
+import { useClient as _useClient } from '@getpara/react-core';
+/** Hook for retrieving the Para client from the provider context. */
+export const useClient = () => _useClient();

package/dist/react-native/ParaMobile.js

@@ -11,6 +11,7 @@ import { ParaCore, Environment, decryptPrivateKeyAndDecryptShare, encryptPrivate
 import { ReactNativeUtils } from './ReactNativeUtils.js';
 import { Passkey, } from 'react-native-passkey';
 import { AuthMethodStatus } from '@getpara/user-management-client';
+import { mapPasskeyError, logPasskeyDiagnostic } from './errors.js';
 import { setEnv } from '../config.js';
 import base64url from 'base64url';
 const ES256_ALGORITHM = -7;
@@ -155,7 +156,15 @@ export class ParaMobile extends ParaCore {
                 timeout: 60000,
                 challenge: base64url.encode('somechallenge'),
             };
-            const result = yield Passkey.create(requestJson);
+            let result;
+            try {
+                result = yield Passkey.create(requestJson);
+            }
+            catch (error) {
+                const enriched = mapPasskeyError(error);
+                logPasskeyDiagnostic(enriched, 'registration', this.relyingPartyId);
+                throw enriched;
+            }
             let resultJson;
             if (typeof result === 'string') {
                 resultJson = JSON.parse(result);
@@ -195,7 +204,15 @@ export class ParaMobile extends ParaCore {
                 rpId: this.relyingPartyId,
                 allowCredentials: (allowedPublicKeys === null || allowedPublicKeys === void 0 ? void 0 : allowedPublicKeys[0]) ? [{ type: 'public-key', id: allowedPublicKeys[0] }] : [],
             };
-            const result = yield Passkey.get(requestJson);
+            let result;
+            try {
+                result = yield Passkey.get(requestJson);
+            }
+            catch (error) {
+                const enriched = mapPasskeyError(error);
+                logPasskeyDiagnostic(enriched, 'login', this.relyingPartyId);
+                throw enriched;
+            }
             let resultJson;
             if (typeof result === 'string') {
                 resultJson = JSON.parse(result);

package/dist/react-native/errors.d.ts

@@ -0,0 +1,18 @@
+export declare const PARA_PASSKEY_ERROR_CODES: readonly ["USER_CANCELLED", "TIMED_OUT", "BAD_CONFIGURATION", "NOT_CONFIGURED", "RP_ID_MISMATCH", "NOT_SUPPORTED", "NO_CREDENTIALS", "REQUEST_FAILED", "INTERRUPTED", "UNKNOWN"];
+export type ParaPasskeyErrorCode = (typeof PARA_PASSKEY_ERROR_CODES)[number];
+export declare class ParaPasskeyError extends Error {
+    readonly code: ParaPasskeyErrorCode;
+    readonly platform: 'ios' | 'android' | 'unknown';
+    readonly suggestion: string;
+    readonly docsUrl: string;
+    constructor(params: {
+        code: ParaPasskeyErrorCode;
+        message: string;
+        platform: 'ios' | 'android' | 'unknown';
+        suggestion: string;
+        docsUrl: string;
+        cause?: unknown;
+    });
+}
+export declare function mapPasskeyError(error: unknown): ParaPasskeyError;
+export declare function logPasskeyDiagnostic(error: ParaPasskeyError, operation: string, relyingPartyId: string): void;

package/dist/react-native/errors.js

@@ -0,0 +1,244 @@
+import { Platform } from 'react-native';
+export const PARA_PASSKEY_ERROR_CODES = [
+    'USER_CANCELLED',
+    'TIMED_OUT',
+    'BAD_CONFIGURATION',
+    'NOT_CONFIGURED',
+    'RP_ID_MISMATCH',
+    'NOT_SUPPORTED',
+    'NO_CREDENTIALS',
+    'REQUEST_FAILED',
+    'INTERRUPTED',
+    'UNKNOWN',
+];
+const DOCS_BASE_URL = 'https://docs.getpara.com/v2/react-native/error-codes';
+export class ParaPasskeyError extends Error {
+    constructor(params) {
+        super(params.message);
+        Object.setPrototypeOf(this, ParaPasskeyError.prototype);
+        this.name = 'ParaPasskeyError';
+        this.code = params.code;
+        this.platform = params.platform;
+        this.suggestion = params.suggestion;
+        this.docsUrl = params.docsUrl;
+        if (params.cause !== undefined) {
+            this.cause = params.cause;
+        }
+    }
+}
+function isPasskeyError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'error' in error &&
+        'message' in error &&
+        typeof error.error === 'string' &&
+        typeof error.message === 'string');
+}
+function detectPlatform() {
+    if (Platform.OS === 'ios')
+        return 'ios';
+    if (Platform.OS === 'android')
+        return 'android';
+    return 'unknown';
+}
+function docsUrlForCode(code) {
+    const fragment = code.toLowerCase();
+    return `${DOCS_BASE_URL}#${fragment}`;
+}
+export function mapPasskeyError(error) {
+    const platform = detectPlatform();
+    if (!isPasskeyError(error)) {
+        const code = 'UNKNOWN';
+        return new ParaPasskeyError({
+            code,
+            message: error instanceof Error ? error.message : String(error),
+            platform,
+            suggestion: "An unexpected error occurred during the passkey operation. Check the 'cause' property for details.",
+            docsUrl: docsUrlForCode(code),
+            cause: error,
+        });
+    }
+    const errorField = error.error;
+    const messageField = error.message;
+    switch (errorField) {
+        case 'UserCancelled': {
+            const code = 'USER_CANCELLED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The user dismissed the passkey prompt. Handle this gracefully and allow the user to retry.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'TimedOut': {
+            const code = 'TIMED_OUT';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The passkey operation timed out. Ensure the user completes the biometric prompt within the timeout period.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'BadConfiguration': {
+            const code = 'BAD_CONFIGURATION';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'App entitlements or associated domains are misconfigured. Verify your webcredentials entries and confirm your Team ID + Bundle ID is registered in the Developer Portal.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'NotConfigured': {
+            const code = 'NOT_CONFIGURED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The credential provider is not configured. Ensure Google Play Services is available and a Google account is signed in on the device.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'NotSupported': {
+            const code = 'NOT_SUPPORTED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'Passkeys are not supported on this device. iOS 16+ or Android API 28+ is required.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'NoCredentials': {
+            const code = 'NO_CREDENTIALS';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'No passkeys found for this user on this device. The user may need to register a passkey first or is on a different device.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'RequestFailed': {
+            const code = 'REQUEST_FAILED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The passkey request failed. On iOS, check associated domains and Team ID + Bundle ID registration. On Android, verify your SHA-256 fingerprint in the Developer Portal.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'Interrupted': {
+            const code = 'INTERRUPTED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The passkey operation was interrupted and may be retried.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'InvalidChallenge': {
+            const code = 'BAD_CONFIGURATION';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The challenge provided to the passkey request was invalid. This is likely an SDK internal issue.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'InvalidUser':
+        case 'InvalidUserId': {
+            const code = 'BAD_CONFIGURATION';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The user ID provided to the passkey request was invalid. This is likely an SDK internal issue.',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'HandlerUndefined': {
+            const code = 'NOT_SUPPORTED';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: 'The passkey handler is not available. This typically means the iOS version does not support passkeys (requires iOS 16+).',
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'Native error': {
+            const gpsMatch = /\[(\d+)\]/.exec(messageField);
+            if (gpsMatch && gpsMatch[1] === '50152') {
+                const code = 'RP_ID_MISMATCH';
+                return new ParaPasskeyError({
+                    code,
+                    message: messageField,
+                    platform,
+                    suggestion: "Your app's signing certificate SHA-256 fingerprint doesn't match what's registered in the Developer Portal. Debug and release builds use different signing keys. Run 'keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android' to get your debug fingerprint, then register it in the Developer Portal.",
+                    docsUrl: docsUrlForCode(code),
+                    cause: error,
+                });
+            }
+            const code = 'UNKNOWN';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: "An unrecognized native passkey error occurred. Check the 'cause' property for the original error details.",
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        case 'UnknownError':
+        case 'Unknown error': {
+            const code = 'UNKNOWN';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: "An unknown passkey error occurred. Check the 'cause' property for details.",
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+        default: {
+            const code = 'UNKNOWN';
+            return new ParaPasskeyError({
+                code,
+                message: messageField,
+                platform,
+                suggestion: "An unexpected error occurred during the passkey operation. Check the 'cause' property for details.",
+                docsUrl: docsUrlForCode(code),
+                cause: error,
+            });
+        }
+    }
+}
+export function logPasskeyDiagnostic(error, operation, relyingPartyId) {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.error(`[Para] Passkey ${operation} failed\n` +
+            `  Code:       ${error.code}\n` +
+            `  Platform:   ${error.platform}\n` +
+            `  Message:    ${error.message}\n` +
+            `  RP ID:      ${relyingPartyId}\n` +
+            `  Suggestion: ${error.suggestion}\n` +
+            `  Docs:       ${error.docsUrl}`);
+    }
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@getpara/react-native-wallet",
   "description": "Para Wallet for React Native",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "author": "Para Team <hello@getpara.com> (https://getpara.com)",
   "dependencies": {
-    "@getpara/core-sdk": "2.22.0",
-    "@getpara/react-core": "2.22.0",
-    "@getpara/user-management-client": "2.22.0",
-    "@getpara/viem-v2-integration": "2.22.0",
-    "@getpara/web-sdk": "2.22.0",
+    "@getpara/core-sdk": "2.24.0",
+    "@getpara/react-core": "2.24.0",
+    "@getpara/user-management-client": "2.24.0",
+    "@getpara/viem-v2-integration": "2.24.0",
+    "@getpara/web-sdk": "2.24.0",
     "@peculiar/webcrypto": "^1.5.0",
     "@ungap/structured-clone": "1.3.0",
     "react-native-url-polyfill": "2.0.0",
@@ -222,5 +222,5 @@
       ]
     }
   },
-  "gitHead": "7191b8c823ec592eb1da16c9a085f8e69c6bf377"
+  "gitHead": "3ea729c9a5e550c2053c5fff07d1ca7d8a8f9ce9"
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from '@getpara/web-sdk';
 export { ParaMobile } from './react-native/ParaMobile.js';
+export { ParaPasskeyError, type ParaPasskeyErrorCode, PARA_PASSKEY_ERROR_CODES } from './react-native/errors.js';
 
 // Smart Account types — type-only re-export so Metro doesn't bundle viem for non-AA users
 export type * from '@getpara/viem-v2-integration/aa';
@@ -9,3 +10,8 @@ export * from './provider/index.js';
 
 // Core provider hooks and config types — platform-agnostic, work with any ParaCore subclass
 export * from '@getpara/react-core';
+
+import { useClient as _useClient } from '@getpara/react-core';
+import type { ParaMobile as _ParaMobile } from './react-native/ParaMobile.js';
+/** Hook for retrieving the Para client from the provider context. */
+export const useClient = () => _useClient<_ParaMobile>();

package/src/react-native/ParaMobile.ts

@@ -24,6 +24,7 @@ import {
   PasskeyGetResult,
 } from 'react-native-passkey';
 import { CurrentWalletIds, AuthMethodStatus, TWalletScheme } from '@getpara/user-management-client';
+import { mapPasskeyError, logPasskeyDiagnostic } from './errors.js';
 import { setEnv } from '../config.js';
 import base64url from 'base64url';
 
@@ -196,7 +197,14 @@ export class ParaMobile extends ParaCore {
       challenge: base64url.encode('somechallenge'),
     };
 
-    const result: PasskeyCreateResult = await Passkey.create(requestJson);
+    let result: PasskeyCreateResult;
+    try {
+      result = await Passkey.create(requestJson);
+    } catch (error: unknown) {
+      const enriched = mapPasskeyError(error);
+      logPasskeyDiagnostic(enriched, 'registration', this.relyingPartyId);
+      throw enriched;
+    }
     let resultJson;
 
     if (typeof result === 'string') {
@@ -243,7 +251,14 @@ export class ParaMobile extends ParaCore {
       allowCredentials: allowedPublicKeys?.[0] ? [{ type: 'public-key', id: allowedPublicKeys[0] }] : [],
     };
 
-    const result: PasskeyGetResult = await Passkey.get(requestJson);
+    let result: PasskeyGetResult;
+    try {
+      result = await Passkey.get(requestJson);
+    } catch (error: unknown) {
+      const enriched = mapPasskeyError(error);
+      logPasskeyDiagnostic(enriched, 'login', this.relyingPartyId);
+      throw enriched;
+    }
 
     let resultJson;
 

package/src/react-native/errors.ts

@@ -0,0 +1,297 @@
+import { Platform } from 'react-native';
+
+export const PARA_PASSKEY_ERROR_CODES = [
+  'USER_CANCELLED',
+  'TIMED_OUT',
+  'BAD_CONFIGURATION',
+  'NOT_CONFIGURED',
+  'RP_ID_MISMATCH',
+  'NOT_SUPPORTED',
+  'NO_CREDENTIALS',
+  'REQUEST_FAILED',
+  'INTERRUPTED',
+  'UNKNOWN',
+] as const;
+
+export type ParaPasskeyErrorCode = (typeof PARA_PASSKEY_ERROR_CODES)[number];
+
+const DOCS_BASE_URL = 'https://docs.getpara.com/v2/react-native/error-codes';
+
+export class ParaPasskeyError extends Error {
+  readonly code: ParaPasskeyErrorCode;
+  readonly platform: 'ios' | 'android' | 'unknown';
+  readonly suggestion: string;
+  readonly docsUrl: string;
+
+  constructor(params: {
+    code: ParaPasskeyErrorCode;
+    message: string;
+    platform: 'ios' | 'android' | 'unknown';
+    suggestion: string;
+    docsUrl: string;
+    cause?: unknown;
+  }) {
+    super(params.message);
+    Object.setPrototypeOf(this, ParaPasskeyError.prototype);
+    this.name = 'ParaPasskeyError';
+    this.code = params.code;
+    this.platform = params.platform;
+    this.suggestion = params.suggestion;
+    this.docsUrl = params.docsUrl;
+    if (params.cause !== undefined) {
+      (this as unknown as { cause: unknown }).cause = params.cause;
+    }
+  }
+}
+
+interface PasskeyErrorShape {
+  error: string;
+  message: string;
+}
+
+function isPasskeyError(error: unknown): error is PasskeyErrorShape {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'error' in error &&
+    'message' in error &&
+    typeof (error as Record<string, unknown>).error === 'string' &&
+    typeof (error as Record<string, unknown>).message === 'string'
+  );
+}
+
+function detectPlatform(): 'ios' | 'android' | 'unknown' {
+  if (Platform.OS === 'ios') return 'ios';
+  if (Platform.OS === 'android') return 'android';
+  return 'unknown';
+}
+
+function docsUrlForCode(code: ParaPasskeyErrorCode): string {
+  const fragment = code.toLowerCase();
+  return `${DOCS_BASE_URL}#${fragment}`;
+}
+
+export function mapPasskeyError(error: unknown): ParaPasskeyError {
+  const platform = detectPlatform();
+
+  if (!isPasskeyError(error)) {
+    const code: ParaPasskeyErrorCode = 'UNKNOWN';
+    return new ParaPasskeyError({
+      code,
+      message: error instanceof Error ? error.message : String(error),
+      platform,
+      suggestion: "An unexpected error occurred during the passkey operation. Check the 'cause' property for details.",
+      docsUrl: docsUrlForCode(code),
+      cause: error,
+    });
+  }
+
+  const errorField = error.error;
+  const messageField = error.message;
+
+  switch (errorField) {
+    case 'UserCancelled': {
+      const code: ParaPasskeyErrorCode = 'USER_CANCELLED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: 'The user dismissed the passkey prompt. Handle this gracefully and allow the user to retry.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'TimedOut': {
+      const code: ParaPasskeyErrorCode = 'TIMED_OUT';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'The passkey operation timed out. Ensure the user completes the biometric prompt within the timeout period.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'BadConfiguration': {
+      const code: ParaPasskeyErrorCode = 'BAD_CONFIGURATION';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'App entitlements or associated domains are misconfigured. Verify your webcredentials entries and confirm your Team ID + Bundle ID is registered in the Developer Portal.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'NotConfigured': {
+      const code: ParaPasskeyErrorCode = 'NOT_CONFIGURED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'The credential provider is not configured. Ensure Google Play Services is available and a Google account is signed in on the device.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'NotSupported': {
+      const code: ParaPasskeyErrorCode = 'NOT_SUPPORTED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: 'Passkeys are not supported on this device. iOS 16+ or Android API 28+ is required.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'NoCredentials': {
+      const code: ParaPasskeyErrorCode = 'NO_CREDENTIALS';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'No passkeys found for this user on this device. The user may need to register a passkey first or is on a different device.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'RequestFailed': {
+      const code: ParaPasskeyErrorCode = 'REQUEST_FAILED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'The passkey request failed. On iOS, check associated domains and Team ID + Bundle ID registration. On Android, verify your SHA-256 fingerprint in the Developer Portal.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'Interrupted': {
+      const code: ParaPasskeyErrorCode = 'INTERRUPTED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: 'The passkey operation was interrupted and may be retried.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'InvalidChallenge': {
+      const code: ParaPasskeyErrorCode = 'BAD_CONFIGURATION';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: 'The challenge provided to the passkey request was invalid. This is likely an SDK internal issue.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'InvalidUser':
+    case 'InvalidUserId': {
+      const code: ParaPasskeyErrorCode = 'BAD_CONFIGURATION';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: 'The user ID provided to the passkey request was invalid. This is likely an SDK internal issue.',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'HandlerUndefined': {
+      const code: ParaPasskeyErrorCode = 'NOT_SUPPORTED';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          'The passkey handler is not available. This typically means the iOS version does not support passkeys (requires iOS 16+).',
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'Native error': {
+      const gpsMatch = /\[(\d+)\]/.exec(messageField);
+      if (gpsMatch && gpsMatch[1] === '50152') {
+        const code: ParaPasskeyErrorCode = 'RP_ID_MISMATCH';
+        return new ParaPasskeyError({
+          code,
+          message: messageField,
+          platform,
+          suggestion:
+            "Your app's signing certificate SHA-256 fingerprint doesn't match what's registered in the Developer Portal. Debug and release builds use different signing keys. Run 'keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android' to get your debug fingerprint, then register it in the Developer Portal.",
+          docsUrl: docsUrlForCode(code),
+          cause: error,
+        });
+      }
+      const code: ParaPasskeyErrorCode = 'UNKNOWN';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion:
+          "An unrecognized native passkey error occurred. Check the 'cause' property for the original error details.",
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    case 'UnknownError':
+    case 'Unknown error': {
+      const code: ParaPasskeyErrorCode = 'UNKNOWN';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: "An unknown passkey error occurred. Check the 'cause' property for details.",
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+
+    default: {
+      const code: ParaPasskeyErrorCode = 'UNKNOWN';
+      return new ParaPasskeyError({
+        code,
+        message: messageField,
+        platform,
+        suggestion: "An unexpected error occurred during the passkey operation. Check the 'cause' property for details.",
+        docsUrl: docsUrlForCode(code),
+        cause: error,
+      });
+    }
+  }
+}
+
+export function logPasskeyDiagnostic(error: ParaPasskeyError, operation: string, relyingPartyId: string): void {
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    console.error(
+      `[Para] Passkey ${operation} failed\n` +
+        `  Code:       ${error.code}\n` +
+        `  Platform:   ${error.platform}\n` +
+        `  Message:    ${error.message}\n` +
+        `  RP ID:      ${relyingPartyId}\n` +
+        `  Suggestion: ${error.suggestion}\n` +
+        `  Docs:       ${error.docsUrl}`,
+    );
+  }
+}