@lombard.finance/sdk 4.0.0 → 4.1.2

package/src/shared/errors.ts

@@ -1,405 +0,0 @@
-/**
- * Error handling for the Lombard SDK
- *
- * This module defines a comprehensive error system with:
- * - Type-safe error codes
- * - Rich metadata support
- * - Factory methods for common errors
- * - JSON serialization for logging
- * - SDK version for debugging
- * - Sentry-compatible context extraction
- */
-
-import { SDK_VERSION } from '../version';
-
-/**
- * General error codes
- */
-export enum ErrorCode {
-  UNKNOWN_ERROR = 'unknown-error',
-  INVALID_CONFIGURATION = 'invalid-configuration',
-  OPERATION_TIMEOUT = 'operation-timeout',
-  OPERATION_CANCELLED = 'operation-cancelled',
-}
-
-/**
- * Provider-related error codes
- */
-export enum ProviderErrorCode {
-  PROVIDER_MISSING = 'provider-missing',
-  PROVIDER_INITIALIZATION_FAILED = 'provider-initialization-failed',
-  PROVIDER_CALL_FAILED = 'provider-call-failed',
-  SIGNER_MISSING = 'signer-missing',
-  USER_REJECTED = 'user-rejected',
-  NETWORK_MISMATCH = 'network-mismatch',
-}
-
-/**
- * Registry-related error codes
- */
-export enum RegistryErrorCode {
-  ROUTE_NOT_FOUND = 'route-not-found',
-  INVALID_ROUTE_DEFINITION = 'invalid-route-definition',
-  UNSUPPORTED_CHAIN = 'unsupported-chain',
-  UNSUPPORTED_ASSET = 'unsupported-asset',
-  INCOMPATIBLE_ROUTE = 'incompatible-route',
-  ENVIRONMENT_MISMATCH = 'environment-mismatch',
-}
-
-/**
- * Validation error codes
- */
-export enum ValidationErrorCode {
-  INVALID_ADDRESS = 'invalid-address',
-  INVALID_AMOUNT = 'invalid-amount',
-  AMOUNT_TOO_SMALL = 'amount-too-small',
-  AMOUNT_TOO_LARGE = 'amount-too-large',
-  INSUFFICIENT_BALANCE = 'insufficient-balance',
-  INVALID_PARAMETER = 'invalid-parameter',
-  MISSING_REQUIRED_PARAMETER = 'missing-required-parameter',
-  INVALID_CHAIN = 'invalid-chain',
-  INVALID_STATE = 'invalid-state',
-  INVALID_ASSET = 'invalid-asset',
-}
-
-/**
- * Contract interaction error codes
- */
-export enum ContractErrorCode {
-  CONTRACT_CALL_FAILED = 'contract-call-failed',
-  TRANSACTION_FAILED = 'transaction-failed',
-  TRANSACTION_REVERTED = 'transaction-reverted',
-  APPROVAL_FAILED = 'approval-failed',
-  INSUFFICIENT_ALLOWANCE = 'insufficient-allowance',
-  GAS_ESTIMATION_FAILED = 'gas-estimation-failed',
-}
-
-/**
- * Union type of all error codes
- */
-export type AnyErrorCode =
-  | ErrorCode
-  | ProviderErrorCode
-  | RegistryErrorCode
-  | ValidationErrorCode
-  | ContractErrorCode;
-
-/**
- * Lombard SDK Error class
- *
- * Custom error class that extends Error with additional properties:
- * - Machine-readable error code
- * - Rich metadata for debugging
- * - JSON serialization support
- *
- * @example
- * ```typescript
- * throw new LombardError(
- *   ProviderErrorCode.PROVIDER_MISSING,
- *   'EVM provider not configured',
- *   { chain: 'ethereum', requiredProvider: 'evm' }
- * );
- * ```
- */
-export class LombardError extends Error {
-  /** Machine-readable error code */
-  public readonly code: AnyErrorCode;
-
-  /** Additional metadata for debugging */
-  public readonly metadata?: Record<string, unknown>;
-
-  /** SDK version when error occurred (for debugging) */
-  public readonly sdkVersion: string = SDK_VERSION;
-
-  /** Timestamp when error occurred */
-  public readonly timestamp: string = new Date().toISOString();
-
-  constructor(
-    code: AnyErrorCode,
-    message: string,
-    metadata?: Record<string, unknown>,
-  ) {
-    super(message);
-    this.name = 'LombardError';
-    this.code = code;
-    this.metadata = metadata;
-
-    // Maintains proper stack trace for where our error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, LombardError);
-    }
-  }
-
-  /**
-   * Serialize error to JSON for logging
-   *
-   * Includes all context needed for debugging: code, message, metadata,
-   * SDK version, timestamp, and stack trace.
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   await action.execute();
-   * } catch (error) {
-   *   if (error instanceof LombardError) {
-   *     console.log(JSON.stringify(error.toJSON(), null, 2));
-   *   }
-   * }
-   * ```
-   */
-  toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      sdkVersion: this.sdkVersion,
-      timestamp: this.timestamp,
-      ...(this.metadata && { metadata: this.metadata }),
-      ...(this.stack && { stack: this.stack }),
-    };
-  }
-
-  /**
-   * Get Sentry-compatible context for error reporting
-   *
-   * Returns an object suitable for Sentry's `extra` or `contexts` fields.
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   await action.execute();
-   * } catch (error) {
-   *   if (error instanceof LombardError) {
-   *     Sentry.captureException(error, {
-   *       contexts: { lombard: error.toSentryContext() },
-   *     });
-   *   }
-   * }
-   * ```
-   */
-  toSentryContext(): Record<string, unknown> {
-    return {
-      'sdk.version': this.sdkVersion,
-      'error.code': this.code,
-      'error.timestamp': this.timestamp,
-      ...this.metadata,
-    };
-  }
-
-  /**
-   * Factory: Invalid configuration error
-   */
-  static invalidConfiguration(message: string): LombardError {
-    return new LombardError(ErrorCode.INVALID_CONFIGURATION, message);
-  }
-
-  /**
-   * Factory: Provider missing error
-   */
-  static providerMissing(chain: string, providerType: string): LombardError {
-    return new LombardError(
-      ProviderErrorCode.PROVIDER_MISSING,
-      `${providerType} provider not configured for chain ${chain}. Please provide a provider via SDK initialization.`,
-      { chain, providerType },
-    );
-  }
-
-  static moduleMissing(moduleId: string): LombardError {
-    return new LombardError(
-      ValidationErrorCode.INVALID_PARAMETER,
-      `Module "${moduleId}" is not registered. Install and register the corresponding package via createConfig({ modules: [...] }).`,
-      { moduleId },
-    );
-  }
-
-  /**
-   * Factory: Provider call failed error
-   */
-  static providerCallFailed(
-    method: string,
-    cause: Error | string,
-  ): LombardError {
-    const causeMessage = cause instanceof Error ? cause.message : cause;
-    return new LombardError(
-      ProviderErrorCode.PROVIDER_CALL_FAILED,
-      `Provider method ${method} failed: ${causeMessage}`,
-      { method, cause: causeMessage },
-    );
-  }
-
-  /**
-   * Factory: User rejected transaction
-   */
-  static userRejected(operation: string): LombardError {
-    return new LombardError(
-      ProviderErrorCode.USER_REJECTED,
-      `User rejected ${operation}. Please try again and approve the transaction in your wallet.`,
-      { operation },
-    );
-  }
-
-  /**
-   * Factory: Route not found in registry
-   */
-  static routeNotFound(params: Record<string, unknown>): LombardError {
-    return new LombardError(
-      RegistryErrorCode.ROUTE_NOT_FOUND,
-      'No route found matching the provided parameters. Please verify the asset and chain combination is supported.',
-      params,
-    );
-  }
-
-  /**
-   * Factory: Invalid route definition
-   */
-  static invalidRouteDefinition(reason: string): LombardError {
-    return new LombardError(
-      RegistryErrorCode.INVALID_ROUTE_DEFINITION,
-      `Invalid route definition: ${reason}`,
-      { reason },
-    );
-  }
-
-  /**
-   * Factory: Unsupported chain
-   */
-  static unsupportedChain(chain: string): LombardError {
-    return new LombardError(
-      RegistryErrorCode.UNSUPPORTED_CHAIN,
-      `Chain ${chain} is not supported in the current environment.`,
-      { chain },
-    );
-  }
-
-  /**
-   * Factory: Invalid parameter
-   */
-  static invalidParameter(parameter: string, reason: string): LombardError {
-    return new LombardError(ValidationErrorCode.INVALID_PARAMETER, reason, {
-      parameter,
-    });
-  }
-
-  /**
-   * Factory: Invalid address
-   */
-  static invalidAddress(address: string, chain?: string): LombardError {
-    return new LombardError(
-      ValidationErrorCode.INVALID_ADDRESS,
-      `Invalid address format: ${address}${chain ? ` for chain ${chain}` : ''}`,
-      { address, chain },
-    );
-  }
-
-  /**
-   * Factory: Invalid amount
-   */
-  static invalidAmount(reason: string): LombardError {
-    return new LombardError(ValidationErrorCode.INVALID_AMOUNT, reason, {
-      reason,
-    });
-  }
-
-  /**
-   * Factory: Amount too small
-   */
-  static amountTooSmall(
-    amount: string,
-    minimum: string,
-    asset: string,
-  ): LombardError {
-    return new LombardError(
-      ValidationErrorCode.AMOUNT_TOO_SMALL,
-      `Amount ${amount} is below minimum ${minimum} ${asset}`,
-      { amount, minimum, asset },
-    );
-  }
-
-  /**
-   * Factory: Insufficient balance
-   */
-  static insufficientBalance(
-    required: string,
-    available: string,
-    asset: string,
-  ): LombardError {
-    return new LombardError(
-      ValidationErrorCode.INSUFFICIENT_BALANCE,
-      `Insufficient ${asset} balance. Required: ${required}, Available: ${available}`,
-      { required, available, asset },
-    );
-  }
-
-  /**
-   * Factory: Missing required parameter
-   */
-  static missingParameter(parameterName: string): LombardError {
-    return new LombardError(
-      ValidationErrorCode.MISSING_REQUIRED_PARAMETER,
-      `Required parameter "${parameterName}" is missing`,
-      { parameterName },
-    );
-  }
-
-  /**
-   * Factory: Transaction failed
-   */
-  static transactionFailed(txHash: string, reason: string): LombardError {
-    return new LombardError(
-      ContractErrorCode.TRANSACTION_FAILED,
-      `Transaction failed: ${reason}`,
-      { txHash, reason },
-    );
-  }
-
-  /**
-   * Factory: Transaction reverted
-   */
-  static transactionReverted(
-    txHash: string,
-    revertReason?: string,
-  ): LombardError {
-    return new LombardError(
-      ContractErrorCode.TRANSACTION_REVERTED,
-      `Transaction reverted${revertReason ? `: ${revertReason}` : ''}`,
-      { txHash, revertReason },
-    );
-  }
-
-  /**
-   * Factory: Approval failed
-   */
-  static approvalFailed(token: string, spender: string): LombardError {
-    return new LombardError(
-      ContractErrorCode.APPROVAL_FAILED,
-      `Failed to approve ${token} for spender ${spender}`,
-      { token, spender },
-    );
-  }
-}
-
-/**
- * Type guard to check if an error is a LombardError
- */
-export function isLombardError(error: unknown): error is LombardError {
-  return error instanceof LombardError;
-}
-
-/**
- * Helper to wrap unknown errors as LombardError
- */
-export function wrapError(error: unknown): LombardError {
-  if (isLombardError(error)) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    return new LombardError(ErrorCode.UNKNOWN_ERROR, error.message, {
-      originalError: error.stack,
-    });
-  }
-
-  return new LombardError(ErrorCode.UNKNOWN_ERROR, String(error), {
-    originalValue: error,
-  });
-}

package/src/shared/events.ts

@@ -1,260 +0,0 @@
-/**
- * Event definitions for all strategy types
- *
- * This module defines strongly-typed events that strategies emit
- * during their execution lifecycle.
- */
-
-import type { StrategyProgress } from '../core/types';
-import type { LombardError } from './errors';
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Event emitter requires bivariant `any` for type-safe event handler signatures
-type StrategyEventHandlerMap = Record<string, (...args: any[]) => void>;
-
-/**
- * Stake operation events
- *
- * Emitted by all stake strategies (BTC → LBTC, etc.)
- */
-export const StakeEvent = {
-  /** Progress update with detailed step information */
-  Progress: 'progress',
-
-  /** Status change (e.g., 'idle' → 'preparing' → 'ready') */
-  StatusChange: 'status-change',
-
-  /** Operation completed successfully */
-  Completed: 'completed',
-
-  /** Operation failed */
-  Failed: 'failed',
-
-  /** Error occurred */
-  Error: 'error',
-} as const;
-
-export type StakeEvent = (typeof StakeEvent)[keyof typeof StakeEvent];
-
-/**
- * Deposit operation events
- *
- * Emitted by all deposit strategies (EVM, etc.)
- */
-export const DepositEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type DepositEvent = (typeof DepositEvent)[keyof typeof DepositEvent];
-
-/**
- * Redeem operation events
- *
- * Emitted by all redeem strategies (cross-chain asset redemptions)
- */
-export const RedeemEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type RedeemEvent = (typeof RedeemEvent)[keyof typeof RedeemEvent];
-
-/**
- * Unstake operation events
- *
- * Emitted by all unstake strategies (LBTC → BTC or BTC.b)
- */
-export const UnstakeEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type UnstakeEvent = (typeof UnstakeEvent)[keyof typeof UnstakeEvent];
-
-/**
- * Deploy operation events
- *
- * Emitted by deploy strategies (deploying L-Assets to DeFi protocols)
- */
-export const DeployEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type DeployEvent = (typeof DeployEvent)[keyof typeof DeployEvent];
-
-/**
- * Bridge operation events
- *
- * Emitted by bridge strategies (cross-chain L-Asset transfers)
- */
-export const BridgeEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type BridgeEvent = (typeof BridgeEvent)[keyof typeof BridgeEvent];
-
-/**
- * StakeAndDeploy operation events ("Stake and Bake")
- *
- * Emitted by stake-and-deploy strategies (BTC → LBTC → Vault in one operation)
- */
-export const StakeAndDeployEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type StakeAndDeployEvent =
-  (typeof StakeAndDeployEvent)[keyof typeof StakeAndDeployEvent];
-
-/**
- * DepositAndDeploy operation events
- *
- * Emitted by deposit-and-deploy strategies (BTC → BTC.b → Vault in one operation)
- * Similar to StakeAndDeploy but produces BTC.b instead of LBTC.
- */
-export const DepositAndDeployEvent = {
-  Progress: 'progress',
-  StatusChange: 'status-change',
-  Completed: 'completed',
-  Failed: 'failed',
-  Error: 'error',
-} as const;
-
-export type DepositAndDeployEvent =
-  (typeof DepositAndDeployEvent)[keyof typeof DepositAndDeployEvent];
-
-/**
- * Event handler type mapping for stake operations
- */
-export interface StakeEventMap extends StrategyEventHandlerMap {
-  [StakeEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [StakeEvent.StatusChange]: (status: string) => void;
-  [StakeEvent.Completed]: () => void;
-  [StakeEvent.Failed]: () => void;
-  [StakeEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for deposit operations
- */
-export interface DepositEventMap extends StrategyEventHandlerMap {
-  [DepositEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [DepositEvent.StatusChange]: (status: string) => void;
-  [DepositEvent.Completed]: () => void;
-  [DepositEvent.Failed]: () => void;
-  [DepositEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for redeem operations
- */
-export interface RedeemEventMap extends StrategyEventHandlerMap {
-  [RedeemEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [RedeemEvent.StatusChange]: (status: string) => void;
-  [RedeemEvent.Completed]: () => void;
-  [RedeemEvent.Failed]: () => void;
-  [RedeemEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for unstake operations
- */
-export interface UnstakeEventMap extends StrategyEventHandlerMap {
-  [UnstakeEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [UnstakeEvent.StatusChange]: (status: string) => void;
-  [UnstakeEvent.Completed]: () => void;
-  [UnstakeEvent.Failed]: () => void;
-  [UnstakeEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for deploy operations
- */
-export interface DeployEventMap extends StrategyEventHandlerMap {
-  [DeployEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [DeployEvent.StatusChange]: (status: string) => void;
-  [DeployEvent.Completed]: () => void;
-  [DeployEvent.Failed]: () => void;
-  [DeployEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for bridge operations
- */
-export interface BridgeEventMap extends StrategyEventHandlerMap {
-  [BridgeEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [BridgeEvent.StatusChange]: (status: string) => void;
-  [BridgeEvent.Completed]: () => void;
-  [BridgeEvent.Failed]: () => void;
-  [BridgeEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for stake-and-deploy operations
- */
-export interface StakeAndDeployEventMap extends StrategyEventHandlerMap {
-  [StakeAndDeployEvent.Progress]: (progress: StrategyProgress<string>) => void;
-  [StakeAndDeployEvent.StatusChange]: (status: string) => void;
-  [StakeAndDeployEvent.Completed]: () => void;
-  [StakeAndDeployEvent.Failed]: () => void;
-  [StakeAndDeployEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Event handler type mapping for deposit-and-deploy operations
- */
-export interface DepositAndDeployEventMap extends StrategyEventHandlerMap {
-  [DepositAndDeployEvent.Progress]: (
-    progress: StrategyProgress<string>,
-  ) => void;
-  [DepositAndDeployEvent.StatusChange]: (status: string) => void;
-  [DepositAndDeployEvent.Completed]: () => void;
-  [DepositAndDeployEvent.Failed]: () => void;
-  [DepositAndDeployEvent.Error]: (error: LombardError) => void;
-}
-
-/**
- * Generic event map type for any strategy
- */
-export type StrategyEventMap =
-  | StakeEventMap
-  | DepositEventMap
-  | RedeemEventMap
-  | UnstakeEventMap
-  | DeployEventMap
-  | BridgeEventMap
-  | StakeAndDeployEventMap
-  | DepositAndDeployEventMap;
-
-/**
- * Generic event type for any strategy
- */
-export type StrategyEvent =
-  | StakeEvent
-  | DepositEvent
-  | RedeemEvent
-  | UnstakeEvent
-  | DeployEvent
-  | BridgeEvent
-  | StakeAndDeployEvent
-  | DepositAndDeployEvent;