@lombard.finance/sdk 4.0.0 → 4.1.0

package/src/shared/actions/__tests__/BaseAction.test.ts

@@ -1,292 +0,0 @@
-/**
- * Tests for BaseAction abstract class
- */
-
-import { describe, expect, it, vi } from 'vitest';
-
-import type { StrategyProgress } from '../../../core/types';
-import { ErrorCode, LombardError } from '../../errors';
-import { DepositEvent, type DepositEventMap } from '../../events';
-import { BaseAction } from '../BaseAction';
-
-// Concrete implementation for testing
-class TestAction extends BaseAction<DepositEventMap, string> {
-  constructor() {
-    super('idle');
-  }
-
-  // Expose protected methods for testing
-  public testEmitProgress(progress: StrategyProgress<string>): void {
-    this.emitProgress(progress);
-  }
-
-  public testUpdateStatus(status: string): void {
-    this.updateStatus(status);
-  }
-
-  public testEmitCompleted(): void {
-    this.updateStatus('completed');
-    this.emitCompleted();
-  }
-
-  public testEmitFailed(): void {
-    this.updateStatus('failed');
-    this.emitFailed();
-  }
-
-  public testEmitError(error: LombardError): void {
-    this._error = error;
-    this.emitError(error);
-  }
-
-  public testAssertStatus(expected: string | string[], action: string): void {
-    this.assertStatus(expected, action);
-  }
-
-  public testGuard<T>(fn: () => Promise<T>): Promise<T> {
-    return this.act(fn);
-  }
-
-  public testIsFailed(): boolean {
-    return this.isFailed;
-  }
-
-  public testClearError(): void {
-    this.clearError();
-  }
-
-  public testClear(): void {
-    this.clearListeners();
-  }
-}
-
-describe('BaseAction', () => {
-  it('should create an action with initial state', () => {
-    const action = new TestAction();
-    expect(action.status).toBe('idle');
-    expect(action.error).toBeNull();
-  });
-
-  it('should register and call progress handlers', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    action.on(DepositEvent.Progress, handler);
-    action.testEmitProgress({
-      status: 'executing',
-      steps: { approval: 'complete' },
-    });
-
-    expect(handler).toHaveBeenCalledOnce();
-    expect(handler).toHaveBeenCalledWith({
-      status: 'executing',
-      steps: { approval: 'complete' },
-    });
-  });
-
-  it('should register and call status change handlers', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    action.on(DepositEvent.StatusChange, handler);
-    action.testUpdateStatus('ready');
-
-    expect(handler).toHaveBeenCalledOnce();
-    expect(handler).toHaveBeenCalledWith('ready');
-  });
-
-  it('should register and call completed handlers', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    action.on(DepositEvent.Completed, handler);
-    action.testEmitCompleted();
-
-    expect(handler).toHaveBeenCalledOnce();
-  });
-
-  it('should register and call failed handlers', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    action.on(DepositEvent.Failed, handler);
-    action.testEmitFailed();
-
-    expect(handler).toHaveBeenCalledOnce();
-  });
-
-  it('should register and call error handlers', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-    const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
-
-    action.on(DepositEvent.Error, handler);
-    action.testEmitError(error);
-
-    expect(handler).toHaveBeenCalledOnce();
-    expect(handler).toHaveBeenCalledWith(error);
-    expect(action.error).toBe(error);
-  });
-
-  it('should return unsubscribe function from on()', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    const unsubscribe = action.on(DepositEvent.Progress, handler);
-    expect(typeof unsubscribe).toBe('function');
-
-    unsubscribe();
-    action.testEmitProgress({ status: 'ready', steps: {} });
-
-    expect(handler).not.toHaveBeenCalled();
-  });
-
-  it('should support multiple handlers for same event', () => {
-    const action = new TestAction();
-    const handler1 = vi.fn();
-    const handler2 = vi.fn();
-
-    action.on(DepositEvent.Completed, handler1);
-    action.on(DepositEvent.Completed, handler2);
-    action.testEmitCompleted();
-
-    expect(handler1).toHaveBeenCalledOnce();
-    expect(handler2).toHaveBeenCalledOnce();
-  });
-
-  it('should clear all listeners', () => {
-    const action = new TestAction();
-    const progressHandler = vi.fn();
-    const statusHandler = vi.fn();
-    const completedHandler = vi.fn();
-
-    action.on(DepositEvent.Progress, progressHandler);
-    action.on(DepositEvent.StatusChange, statusHandler);
-    action.on(DepositEvent.Completed, completedHandler);
-
-    action.testClear();
-
-    action.testEmitProgress({ status: 'ready', steps: {} });
-    action.testUpdateStatus('ready');
-    action.testEmitCompleted();
-
-    expect(progressHandler).not.toHaveBeenCalled();
-    expect(statusHandler).not.toHaveBeenCalled();
-    expect(completedHandler).not.toHaveBeenCalled();
-  });
-
-  it('should maintain status property', () => {
-    const action = new TestAction();
-    expect(action.status).toBe('idle');
-
-    action.testUpdateStatus('preparing');
-    expect(action.status).toBe('preparing');
-
-    action.testEmitCompleted();
-    expect(action.status).toBe('completed');
-  });
-
-  it('should maintain error property', () => {
-    const action = new TestAction();
-    expect(action.error).toBeNull();
-
-    const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
-    action.testEmitError(error);
-    expect(action.error).toBe(error);
-  });
-
-  it('should handle multiple emissions correctly', () => {
-    const action = new TestAction();
-    const handler = vi.fn();
-
-    action.on(DepositEvent.Progress, handler);
-
-    action.testEmitProgress({ status: 'preparing', steps: {} });
-    action.testEmitProgress({ status: 'ready', steps: {} });
-    action.testEmitProgress({ status: 'executing', steps: {} });
-
-    expect(handler).toHaveBeenCalledTimes(3);
-  });
-
-  describe('assertStatus', () => {
-    it('should pass when status matches single expected', () => {
-      const action = new TestAction();
-      expect(() => action.testAssertStatus('idle', 'test')).not.toThrow();
-    });
-
-    it('should pass when status matches one of expected array', () => {
-      const action = new TestAction();
-      expect(() =>
-        action.testAssertStatus(['idle', 'ready'], 'test'),
-      ).not.toThrow();
-    });
-
-    it('should throw when status does not match', () => {
-      const action = new TestAction();
-      expect(() => action.testAssertStatus('ready', 'test')).toThrow();
-    });
-  });
-
-  describe('act', () => {
-    it('should return result on success', async () => {
-      const action = new TestAction();
-      const result = await action.testGuard(async () => 'success');
-      expect(result).toBe('success');
-    });
-
-    it('should preserve status on failure and set error', async () => {
-      const action = new TestAction();
-      const handler = vi.fn();
-      action.on(DepositEvent.Failed, handler);
-
-      // Set status to 'preparing' before the failure
-      action.testUpdateStatus('preparing');
-
-      await expect(
-        action.testGuard(async () => {
-          throw new Error('test error');
-        }),
-      ).rejects.toThrow();
-
-      // Status should be preserved at 'preparing' (NOT changed to 'failed')
-      expect(action.status).toBe('preparing');
-      expect(action.error).not.toBeNull();
-      expect(action.testIsFailed()).toBe(true);
-      expect(handler).toHaveBeenCalledOnce();
-    });
-
-    it('should clear error on retry', async () => {
-      const action = new TestAction();
-
-      // First call fails
-      await expect(
-        action.testGuard(async () => {
-          throw new Error('test error');
-        }),
-      ).rejects.toThrow();
-
-      expect(action.error).not.toBeNull();
-      expect(action.testIsFailed()).toBe(true);
-
-      // Second call succeeds - error should be cleared
-      const result = await action.testGuard(async () => 'success');
-      expect(result).toBe('success');
-      expect(action.error).toBeNull();
-      expect(action.testIsFailed()).toBe(false);
-    });
-  });
-
-  describe('isFailed', () => {
-    it('should return false when no error', () => {
-      const action = new TestAction();
-      expect(action.testIsFailed()).toBe(false);
-    });
-
-    it('should return true when error is set', () => {
-      const action = new TestAction();
-      const error = new LombardError(ErrorCode.UNKNOWN_ERROR, 'Test error');
-      action.testEmitError(error);
-      expect(action.testIsFailed()).toBe(true);
-    });
-  });
-});

package/src/shared/actions/index.ts

@@ -1,9 +0,0 @@
-/**
- * Shared Actions
- *
- * Base classes and interfaces for action implementations.
- *
- * @module shared/actions
- */
-
-export { BaseAction, type MonitorableAction } from './BaseAction';

package/src/shared/constants/statusConstants.ts

@@ -1,108 +0,0 @@
-/**
- * Status constants for all action types
- *
- * These constants replace magic strings throughout the codebase
- * and provide type-safe status values.
- *
- * ## Error Design
- *
- * Note: There is NO 'failed' status. Error handling is separate from status:
- * - `status` = "What step are you at?" (flow position)
- * - `error` = "Did something go wrong?" (Error | null)
- * - `isFailed` = Derived from `error !== null`
- *
- * When an error occurs, status stays at the step where it happened.
- * This allows:
- * 1. Knowing WHERE the error occurred (status tells you)
- * 2. Easy retry - just call the method again
- * 3. Simpler state machine - status only flows forward
- */
-
-// ═══════════════════════════════════════════════════════════════════════════
-// BTC Actions - Unified Status
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Unified BTC Action Status
- *
- * Single source of truth for all BTC action statuses.
- * All BTC actions (Stake, Deposit, StakeAndDeploy, DepositAndDeploy) use this.
- *
- * Status represents "what step are you at" - no transitional statuses.
- * Use `isLoading` for operation-in-progress state.
- *
- * ## Flow Examples
- *
- * **BtcStake/BtcDeposit (to Ethereum):**
- * IDLE → NEEDS_FEE_AUTHORIZATION → READY → ADDRESS_READY
- *
- * **BtcStake/BtcDeposit (to non-Ethereum):**
- * IDLE → NEEDS_ADDRESS_CONFIRMATION → READY → ADDRESS_READY
- *
- * **BtcStakeAndDeploy/BtcDepositAndDeploy:**
- * IDLE → NEEDS_DEPLOY_AUTHORIZATION → READY → ADDRESS_READY
- */
-export const BtcActionStatus = {
-  /** Initial state - ready for prepare() */
-  IDLE: 'idle',
-
-  // Authorization states (mutually exclusive - action uses one based on config)
-  /** User needs to sign fee authorization (EVM stake/deposit to Ethereum) */
-  NEEDS_FEE_AUTHORIZATION: 'needs_fee_authorization',
-  /** User needs to confirm destination address (non-Ethereum destinations) */
-  NEEDS_ADDRESS_CONFIRMATION: 'needs_address_confirmation',
-  /** User needs to sign vault deploy authorization (stake-and-deploy, deposit-and-deploy) */
-  NEEDS_DEPLOY_AUTHORIZATION: 'needs_deploy_authorization',
-
-  /** Authorization complete - ready to generate address */
-  READY: 'ready',
-
-  /** Deposit address generated - awaiting BTC deposit */
-  ADDRESS_READY: 'address_ready',
-} as const;
-
-export type BtcActionStatus =
-  (typeof BtcActionStatus)[keyof typeof BtcActionStatus];
-
-/**
- * EVM operation statuses (Deposit, Stake, Deploy, Unstake, Redeem)
- *
- * Simplified - use isLoading for operation-in-progress.
- *
- * ## Flow Examples
- *
- * **EVM Unstake (LBTC → BTC.b on Ethereum/Sepolia):**
- * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
- *
- * **EVM Unstake (LBTC → BTC.b on Base/BSC - subsidized):**
- * IDLE → READY → COMPLETED
- *
- * **EVM Redeem (BTC.b → BTC on Ethereum/Sepolia):**
- * IDLE → NEEDS_FEE_AUTHORIZATION → READY → COMPLETED
- */
-export const EvmOperationStatus = {
-  IDLE: 'idle',
-  /** User needs to sign fee authorization (Ethereum/Sepolia only) */
-  NEEDS_FEE_AUTHORIZATION: 'needs_fee_authorization',
-  /** User needs to approve token spending */
-  NEEDS_APPROVAL: 'needs-approval',
-  READY: 'ready',
-  CONFIRMING: 'confirming',
-  COMPLETED: 'completed',
-} as const;
-
-export type EvmOperationStatus =
-  (typeof EvmOperationStatus)[keyof typeof EvmOperationStatus];
-
-/**
- * Solana/Sui/Starknet Unstake operation statuses
- */
-export const NonEvmUnstakeStatus = {
-  IDLE: 'idle',
-  READY: 'ready',
-  CONFIRMING: 'confirming',
-  COMPLETED: 'completed',
-} as const;
-
-export type NonEvmUnstakeStatus =
-  (typeof NonEvmUnstakeStatus)[keyof typeof NonEvmUnstakeStatus];

package/src/shared/context/ContextBuilder.ts

@@ -1,149 +0,0 @@
-/**
- * Context Builder
- *
- * Builds lightweight action contexts from LombardConfig.
- * Contexts are passed to actions instead of the full SDK instance,
- * improving testability and reducing coupling.
- *
- * NOTE: All context creation now works from config only.
- * The SDK class should pass this.config when creating actions.
- *
- * @module shared/context/ContextBuilder
- */
-
-import type {
-  ApiService,
-  BtcService,
-  EvmService,
-  ProviderKey,
-} from '@lombard.finance/sdk-common';
-
-import { PartnerConfiguration } from '../../client/PartnerConfiguration';
-// Note: EvmService is imported for createEvmCoreContext
-import type { LombardConfig } from '../../config/types';
-import { getProviderGetter } from '../../config/types';
-import { CapabilityRegistry } from '../../modules/CapabilityRegistry';
-import type {
-  BtcCoreContext,
-  CoreContext,
-  EvmCoreContext,
-  ProviderResolver,
-} from './types';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Provider Resolution
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Create a provider resolver from config
- */
-function createProviderResolver(config: LombardConfig): ProviderResolver {
-  return async key => {
-    const getter = getProviderGetter(config.providers, key as ProviderKey);
-    if (!getter) {
-      return undefined;
-    }
-    return getter();
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Capability Registry Cache
-// ═══════════════════════════════════════════════════════════════════════════
-
-// Cache capability registries by config to avoid recreating them
-const registryCache = new WeakMap<LombardConfig, CapabilityRegistry>();
-
-/**
- * Get or create capability registry from config
- * @internal
- */
-function getCapabilityRegistry(config: LombardConfig): CapabilityRegistry {
-  let registry = registryCache.get(config);
-  if (!registry) {
-    registry = new CapabilityRegistry(config.modules, config);
-    registryCache.set(config, registry);
-  }
-  return registry;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Context Factories
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Create core context from config
- * @internal
- */
-function createCoreContext(config: LombardConfig): CoreContext {
-  return {
-    env: config.env,
-    partner: new PartnerConfiguration(config.partner),
-    getProvider: createProviderResolver(config),
-    logger: undefined,
-  };
-}
-
-/**
- * Create BTC core context from config
- *
- * Used by BtcActions and BTC factory functions.
- *
- * @example
- * ```typescript
- * // In BtcActions
- * constructor(config: LombardConfig) {
- *   this.ctx = createBtcCoreContext(config);
- * }
- *
- * // Or directly for factory functions
- * const stake = btcStake(config, params);
- * ```
- */
-export function createBtcCoreContext(config: LombardConfig): BtcCoreContext {
-  const baseContext = createCoreContext(config);
-  const registry = getCapabilityRegistry(config);
-
-  // Type assertions needed because registry doesn't know module types at compile time
-  const btc = registry.require('btc') as BtcService;
-  const api = registry.require('api') as ApiService;
-
-  return {
-    ...baseContext,
-    btc,
-    api,
-    capabilities: registry,
-  };
-}
-
-/**
- * Create EVM core context from config
- *
- * Used by EvmActions and EVM factory functions.
- */
-export function createEvmCoreContext(config: LombardConfig): EvmCoreContext {
-  const baseContext = createCoreContext(config);
-  const registry = getCapabilityRegistry(config);
-
-  // Type assertion needed because registry doesn't know module types at compile time
-  const evm = registry.require('evm') as EvmService;
-
-  return {
-    ...baseContext,
-    evm,
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Legacy Exports (for backward compatibility during migration)
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * @deprecated Use createBtcCoreContext(config) instead
- */
-export const createBtcCoreContextFromConfig = createBtcCoreContext;
-
-/**
- * @deprecated Use createEvmCoreContext(config) instead
- */
-export const createEvmCoreContextFromConfig = createEvmCoreContext;

package/src/shared/context/index.ts

@@ -1,8 +0,0 @@
-/**
- * Strategy Context System
- *
- * Exports context types and builder functions for dependency injection.
- */
-
-export * from './ContextBuilder';
-export * from './types';