feat(escrow): implement createEscrowAccount function

[opratem]

Description

Implements the complete createEscrowAccount() function for the Escrow lifecycle SDK. This function assembles all creation steps into a final exported function with full validation, error handling, idempotency checks, and comprehensive documentation.

Related Issue

Fixes #75

Type of Change

• Bug fix
• New feature
• Documentation update
• Code refactoring
• Performance improvement

Changes Made

• Implemented full createEscrowAccount() function with complete lifecycle:
  • Validates adopterPublicKey with isValidPublicKey()
  • Validates ownerPublicKey with isValidPublicKey()
  • Validates depositAmount with isValidAmount()
  • Runs idempotency check before creation (caches by adopter:owner:amount key)
  • Generates new Stellar keypair for escrow account
  • Funds account via Friendbot (testnet)
  • Configures multisig with adopter and owner as signers (weight 1 each)
  • Sets thresholds (low: 1, medium: 2, high: 2)
  • Encodes optional metadata as transaction memo
  • Returns complete EscrowAccount object
• All errors caught and rethrown as typed SdkError subclasses:
  • ValidationError for invalid input parameters
  • FriendbotError for funding failures (retryable)
  • SdkError wrapper for unknown errors
• Added full JSDoc documentation with @param, @returns, @throws, @example
• Added clearEscrowCache() helper for testing purposes
• Exported clearEscrowCache from main index

Testing

• Added comprehensive unit tests with all steps mocked:
  • Validation tests for all input parameters (9 tests)
  • Idempotency tests (2 tests)
  • Happy path full lifecycle tests (3 tests)
  • Error handling tests (4 tests)
  • Multisig configuration tests (2 tests)
• All 98 tests pass
• Mocked @stellar/stellar-sdk (Keypair, Horizon, TransactionBuilder, Operation)
• Mocked global fetch for Friendbot API calls

npm test
# Test Suites: 9 passed, 9 total
# Tests:       98 passed, 98 total

Checklist

• Code follows project style
• Self-reviewed my code
• Commented complex code
• Updated documentation (JSDoc)
• No new warnings
• Added tests (if applicable)

Screenshots (if applicable)

N/A - SDK function, no UI changes

Additional Notes

Function Signature

async function createEscrowAccount(
  params: CreateEscrowParams
): Promise<EscrowAccount>

CreateEscrowParams Interface

interface CreateEscrowParams {
  adopterPublicKey: string;   // Must be valid Stellar public key (G..., 56 chars)
  ownerPublicKey: string;     // Must be valid Stellar public key (G..., 56 chars)
  depositAmount: string;      // Positive number, max 7 decimal places
  adoptionFee?: string;       // Optional
  unlockDate?: Date;          // Optional, included in response if provided
  metadata?: {                // Optional, encoded as memo
    adoptionId: string;
    petId: string;
  };
}

EscrowAccount Response

interface EscrowAccount {
  accountId: string;          // The escrow's public key
  transactionHash: string;    // Multisig setup transaction hash
  signers: Signer[];          // Array of 3 signers (escrow, adopter, owner)
  thresholds: Thresholds;     // { low: 1, medium: 2, high: 2 }
  unlockDate?: Date;          // If provided in params
}

Usage Example

import { createEscrowAccount } from '@petad/stellar-sdk';

const escrow = await createEscrowAccount({
  adopterPublicKey: 'GADOPTER...',
  ownerPublicKey: 'GOWNER...',
  depositAmount: '100.0000000',
  metadata: {
    adoptionId: 'adopt-123',
    petId: 'pet-456',
  },
});

console.log(escrow.accountId);      // Escrow's public key
console.log(escrow.transactionHash); // Multisig setup tx hash

[amina69]

@opratem failed