@keyban/sdk-base/dist/errors.d.ts

Keyban Javascript SDK provides core functionalities for the MPC wallet solution, supporting web and Node.js apps with TypeScript, custom storage, and Ethereum blockchain integration.

/**
 * @module Errors
 */
/**
 * The `KeybanBaseError` class serves as the foundational structure for all custom errors within the Keyban SDK.
 * It extends the native JavaScript `Error` class, providing additional properties to enrich error handling
 * with more context and information.
 * @template T - The enum type representing the specific error category.
 * @remarks
 * This class is intended to be extended by more specific error classes that define particular error types.
 * It standardizes error information, making it easier to handle and debug errors across the SDK.
 * @example
 * ```typescript
 * import { KeybanBaseError, SdkErrorTypes } from '@keyban/sdk';
 *
 * class AddressInvalidError extends KeybanBaseError<SdkErrorTypes.AddressInvalid> {
 *   constructor(instance: string, detail?: string) {
 *     super({
 *       type: SdkErrorTypes.AddressInvalid,
 *       instance,
 *       detail,
 *       title: "Invalid Ethereum Address",
 *       status: 400,
 *     });
 *   }
 * }
 *
 * // Usage in a function
 * function validateAddress(address: string) {
 *   if (!isValidEthereumAddress(address)) {
 *     throw new AddressInvalidError("validateAddress-001", "The provided Ethereum address is not valid.");
 *   }
 * }
 * ```
 */
declare class KeybanBaseError<T extends string> extends Error {
    /**
     * A URI reference that identifies the problem type. This property is mandatory and provides a
     * machine-readable identifier for the error.
     * @example
     * ```typescript
     * error.type // "https://api.prod.keyban.io/errors/address-invalid"
     * ```
     */
    type: T;
    /**
     * A short, human-readable summary of the problem type. It should remain consistent across
     * occurrences of the problem except for localization purposes.
     * @example
     * ```typescript
     * error.title // "Invalid Ethereum Address"
     * ```
     */
    title: string;
    /**
     * A URI reference that identifies the specific occurrence of the problem. This provides a
     * unique identifier for the particular instance of the error.
     * @example
     * ```typescript
     * error.instance // "validateAddress-001"
     * ```
     */
    instance: string;
    /**
     * The HTTP status code generated by the origin server for this occurrence of the problem.
     * It is a numeric value and is included for the convenience of the client.
     * @example
     * ```typescript
     * error.status // 400
     * ```
     */
    status?: number;
    /**
     * A human-readable explanation specific to this occurrence of the problem. This field helps
     * the client understand and potentially correct the issue.
     * @example
     * ```typescript
     * error.detail // "The provided Ethereum address is not valid."
     * ```
     */
    detail?: string;
    /**
     * A timestamp recording the exact date and time when the exception occurred, in ISO8601 format
     * (`YYYY-MM-DDTHH:mm:ss.sssZ`).
     * @example
     * ```typescript
     * error.timestamp // "2024-04-27T12:34:56.789Z"
     * ```
     */
    timestamp: string;
    /**
     * The original error instance, if any. This can be used to trace the root cause of the error.
     * @example
     * ```typescript
     * error.rootError // Original Error instance or additional error details
     * ```
     */
    rootError?: Error | Record<string, unknown>;
    /**
     * Serializes the error instance into a JSON object, including all relevant properties.
     * This is useful for logging, debugging, or transmitting error information.
     * @returns - A JSON representation of the error.
     * @example
     * ```typescript
     * const errorJson = error.toJSON();
     * console.log(errorJson);
     * ```
     */
    toJSON(): {
        type: T;
        title: string;
        instance: string;
        status: number | undefined;
        detail: string | undefined;
        timestamp: string;
        rootError: Error | Record<string, unknown> | undefined;
    };
    /**
     * Creates an instance of `KeybanBaseError`. It initializes the error with the provided properties,
     * sets the error message, and records the timestamp.
     * @param params - The parameters to initialize the error.
     * @param params.type - The specific error type identifier.
     * @param [params.title] - A short summary of the error. Defaults to the `type` if not provided.
     * @param params.instance - A unique identifier for this specific error occurrence.
     * @param [params.rootError] - The original error, if any.
     * @param [params.detail] - A detailed explanation of the error.
     * @param [params.status] - The HTTP status code associated with the error.
     * @example
     * ```typescript
     * const error = new KeybanBaseError({
     *   type: SdkErrorTypes.AddressInvalid,
     *   instance: "validateAddress-001",
     *   detail: "The provided Ethereum address is not valid.",
     *   status: 400,
     * });
     * ```
     */
    constructor({ type, title, instance, rootError, detail, status, }: {
        type: KeybanBaseError<T>["type"];
        title?: KeybanBaseError<T>["title"];
        instance: KeybanBaseError<T>["instance"];
        rootError?: KeybanBaseError<T>["rootError"];
        detail?: KeybanBaseError<T>["detail"];
        status?: KeybanBaseError<T>["status"];
    });
}

/**
 * Error types for cryptographic operations.
 */
declare enum CryptoErrorType {
    GenerateKey = "GenerateKey",
    ExportKey = "ExportKey",
    ImportKey = "ImportKey",
    Encrypt = "Encrypt",
    Decrypt = "Decrypt"
}
/**
 * Error thrown when a cryptographic operation fails.
 * @example
 * throw new CryptoError(CryptoErrorType.Encrypt, "Crypto.encrypt");
 */
declare class CryptoError extends KeybanBaseError<CryptoErrorType> {
    #private;
    static types: typeof CryptoErrorType;
    constructor(type: CryptoErrorType, instance: string, rootError?: Error);
}

/**
 * Error types for iframe API integration.
 */
declare enum IFrameApiErrorType {
    InvalidOrigin = "InvalidOrigin",
    InvalidCall = "InvalidCall"
}
/**
 * Error thrown by the iframe API server/client layer.
 * @example
 * throw new IFrameApiError(IFrameApiErrorType.InvalidOrigin, "ApiServer.checkEventOrigin");
 */
declare class IFrameApiError extends KeybanBaseError<IFrameApiErrorType> {
    #private;
    static types: typeof IFrameApiErrorType;
    constructor(type: IFrameApiErrorType, instance: string, rootError?: Error);
}

/**
 * Error types for JWT handling and validation.
 */
declare enum JwtErrorType {
    InvalidToken = "InvalidToken"
}
/**
 * Error thrown when JWT validation fails or a token is malformed.
 * @example
 * throw new JwtError(JwtErrorType.InvalidToken, "Auth.validateAccessToken");
 */
declare class JwtError extends KeybanBaseError<JwtErrorType> {
    #private;
    static types: typeof JwtErrorType;
    constructor(type: JwtErrorType, instance: string, rootError?: Error);
}

/**
 * @module SDK Errors
 */

/**
 * Enum representing all possible SDK error types.
 *
 * This enumeration defines the various error conditions that can occur within the Keyban SDK.
 * Each error type is associated with a specific scenario, allowing developers to handle errors
 * gracefully and provide meaningful feedback to users.
 * @enum {string}
 */
declare enum SdkErrorTypes {
    /**
     * An unknown transaction error.
     */
    UnknownTransactionError = "UnknownTransactionError",
    /**
     * An unknown error during iframe API call.
     */
    UnknownIframeApiError = "UnknownIframeApiError",
    /**
     * The provided address is invalid.
     *
     * **Description:** The Ethereum address does not conform to the expected format.
     * **Possible Cause:** Typographical errors in the address or incorrect formatting.
     */
    AddressInvalid = "AddressInvalid",
    /**
     * The provided amount is invalid.
     *
     * **Description:** The amount specified for a transaction is not acceptable.
     * **Possible Cause:** Amount is zero, negative, or exceeds allowed limits.
     */
    AmountInvalid = "AmountInvalid",
    /**
     * The amount is required for this operation.
     *
     * **Description:** An operation that requires a monetary amount did not receive one.
     * **Possible Cause:** Missing amount parameter in the function call.
     */
    AmountRequired = "AmountRequired",
    /**
     * The amount provided is irrelevant and should not be provided.
     *
     * **Description:** An operation does not require an amount, but one was supplied.
     * **Possible Cause:** Misuse of the API by providing unnecessary parameters.
     */
    AmountIrrelevant = "AmountIrrelevant",
    /**
     * The recipient address is the same as the sender address.
     *
     * **Description:** A transaction was attempted where the sender and recipient are identical.
     * **Possible Cause:** User error in specifying addresses or attempting redundant transactions.
     */
    RecipientAddressEqualsSender = "RecipientAddressEqualsSender",
    /**
     * Gas estimation failed during transaction processing.
     *
     * **Description:** The SDK was unable to estimate the gas required for a transaction.
     * **Possible Cause:** Network issues, incorrect transaction parameters, or contract errors.
     */
    EstimateGasExecution = "EstimateGasExecution",
    /**
     * The account has insufficient funds to perform the operation.
     *
     * **Description:** The user's account balance is too low to cover the transaction amount and associated fees.
     * **Possible Cause:** Attempting a transaction with an amount exceeding the available balance.
     */
    InsufficientFunds = "InsufficientFunds",
    /**
     * The NFT standard provided is invalid.
     *
     * **Description:** An unsupported NFT standard was specified.
     * **Possible Cause:** Using an NFT standard other than ERC721 or ERC1155.
     */
    InvalidNftStandard = "InvalidNftStandard",
    /**
     * The specified NFT was not found.
     *
     * **Description:** The NFT identified by the provided contract address and token ID does not exist.
     * **Possible Cause:** Incorrect token ID, wrong contract address, or the NFT has been burned.
     */
    NftNotFound = "NftNotFound",
    /**
     * The specified token balance was not found.
     *
     * **Description:** The token balance identified by the provided contract address does not exist.
     * **Possible Cause:** Incorrect wallet address, wrong contract address.
     */
    TokenBalanceNotFound = "TokenBalanceNotFound"
}
/**
 * Class representing an SDK-specific error.
 *
 * The `SdkError` class extends the `KeybanBaseError` to provide detailed error information
 * based on predefined `SdkErrorTypes`. It facilitates consistent error handling across
 * the Keyban SDK by categorizing errors and providing meaningful messages.
 * @augments KeybanBaseError
 */
declare class SdkError extends KeybanBaseError<SdkErrorTypes> {
    #private;
    /**
     * The available SDK error types.
     */
    static types: typeof SdkErrorTypes;
    /**
     * Creates an instance of `SdkError`.
     * @param type - The specific type of SDK error.
     * @param instance - The identifier of the instance where the error occurred.
     * @param [rootError] - The original error that caused this SDK error, if any.
     * @throws {SdkError} Throws an error if an unknown `SdkErrorTypes` is provided.
     * @example
     * ```typescript
     * throw new SdkError(SdkErrorTypes.InsufficientFunds, "transferFunction");
     * ```
     */
    constructor(type: SdkErrorTypes, instance: string, rootError?: Error | Record<string, unknown>);
}

export { CryptoError, CryptoErrorType, IFrameApiError, IFrameApiErrorType, JwtError, JwtErrorType, KeybanBaseError, SdkError, SdkErrorTypes };