closes #142 feat(wallet): improve wallet import validation and safe error handling

[emmyoat]

Summary

Wallet import flows previously failed unclearly when malformed, empty, non-string, or unsupported secret key values were provided.

This PR improves secret key validation across the SDK to reject invalid inputs cleanly with structured, typed errors (PocketPayError with code INVALID_SECRET_KEY) while guaranteeing sensitive key material is redacted and never leaked into error messages, error properties, logs, or stack traces.

---

Key Changes

1. Robust Secret Key Validation (src/utils/index.ts)

• Enhanced validateSecretKey(secretKey: unknown) with explicit preflight checks:
  • Type Check: Non-string values throw PocketPayError with reason: 'not_a_string'.
  • Presence Check: Empty or whitespace-only inputs throw PocketPayError with reason: 'missing'.
  • Prefix Check: Keys not starting with 'S' throw PocketPayError with reason: 'invalid_prefix'.
  • Length Check: Keys not exactly 56 characters long throw PocketPayError with reason: 'invalid_length'.
  • Format Check: Failed strkey checksum/payload verification throws PocketPayError with reason: 'invalid_format'.
• Redaction Guarantee: validation.value is omitted for secret key errors so raw secret values are never exposed in error objects, logs, or serialized output.

2. Safe & Enhanced Import Helpers (src/wallet/index.ts & src/index.ts)

• Updated importWallet and getPublicKey to trim keys and safely wrap keypair derivation errors into PocketPayError.
• Added non-throwing and recovery-hint-enriched import helper functions:
  • safeImportWallet(secretKey) — returns PocketPayResult<WalletKeypair>
  • enhancedImportWallet(secretKey) — returns EnhancedPocketPayResult<WalletKeypair> with action: 'check_input' recovery hints
  • safeEnhancedImportWallet(secretKey) — non-throwing enriched result wrapper

3. Comprehensive Unit Tests (tests/wallet.test.ts)

• Added Vitest test suites covering:
  • Valid secret key import and whitespace trimming.
  • Non-string inputs (null, undefined, numbers, objects, arrays).
  • Empty and whitespace-only strings.
  • Keys with wrong prefix (G...).
  • Keys with invalid length (S1234567890).
  • Keys with bad strkey checksums (S + 55 zeros).
  • Non-throwing safeImportWallet, enhancedImportWallet, and safeEnhancedImportWallet.
  • Explicit assertions verifying secret input is never present in .message, .validation, or JSON serialization.
  • Zero real private keys are used in test files.

4. Documentation Updates

• docs/wallet-import-safety.md: Updated with validation rules, error reasons, redaction policies, and safe import wrapper usage.
• docs/error-handling.md: Updated enhanced operations table and recovery hints for importWallet.
• docs/api-reference.md: Added Wallet Import API reference section for importWallet, safeImportWallet, enhancedImportWallet, and safeEnhancedImportWallet.

---

Acceptance Criteria Checklist

• Wallet import validation is improved with granular reason codes (not_a_string, missing, invalid_prefix, invalid_length, invalid_format).
• Invalid secret keys are rejected safely.
• Sensitive input is not logged or returned in error metadata or messages.
• Tests cover valid, invalid, empty, and malformed inputs.
• Documentation explains expected errors and safe import helpers.
• No real private keys included in test fixtures.