@satoshai/kit 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -3,6 +3,61 @@ import { ClarityValue, TupleCV, PostCondition, PostConditionMode } from '@stacks
 import { ClarityAbi, ExtractAbiFunctionNames, Pretty, ExtractAbiFunction, ClarityAbiArgToPrimitiveTypeValue } from 'clarity-abitype';
 export { ClarityAbi } from 'clarity-abitype';
 
+type BaseErrorType = BaseError & {
+    name: 'StacksKitError';
+};
+declare class BaseError extends Error {
+    name: string;
+    shortMessage: string;
+    constructor(shortMessage: string, options?: {
+        cause?: Error;
+        details?: string;
+    });
+    walk(fn?: (err: unknown) => boolean): unknown;
+}
+type WalletNotConnectedErrorType = WalletNotConnectedError & {
+    name: 'WalletNotConnectedError';
+};
+declare class WalletNotConnectedError extends BaseError {
+    name: string;
+    constructor();
+}
+type WalletNotFoundErrorType = WalletNotFoundError & {
+    name: 'WalletNotFoundError';
+};
+declare class WalletNotFoundError extends BaseError {
+    name: string;
+    wallet: string;
+    constructor({ wallet }: {
+        wallet: string;
+    });
+}
+type UnsupportedMethodErrorType = UnsupportedMethodError & {
+    name: 'UnsupportedMethodError';
+};
+declare class UnsupportedMethodError extends BaseError {
+    name: string;
+    method: string;
+    wallet: string;
+    constructor({ method, wallet }: {
+        method: string;
+        wallet: string;
+    });
+}
+type WalletRequestErrorType = WalletRequestError & {
+    name: 'WalletRequestError';
+};
+declare class WalletRequestError extends BaseError {
+    name: string;
+    method: string;
+    wallet: string;
+    constructor({ method, wallet, cause }: {
+        method: string;
+        wallet: string;
+        cause: Error;
+    });
+}
+
 declare const SUPPORTED_STACKS_WALLETS: readonly ["xverse", "leather", "asigna", "fordefi", "wallet-connect", "okx"];
 type SupportedStacksWallet = (typeof SUPPORTED_STACKS_WALLETS)[number];
 
@@ -116,7 +171,7 @@ declare const useSignMessage: () => {
     signMessageAsync: (variables: SignMessageVariables) => Promise<SignMessageData>;
     reset: () => void;
     data: SignMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -142,7 +197,7 @@ declare const useSignStructuredMessage: () => {
     signStructuredMessageAsync: (variables: SignStructuredMessageVariables) => Promise<SignStructuredMessageData>;
     reset: () => void;
     data: SignStructuredMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -168,7 +223,7 @@ declare const useSignTransaction: () => {
     signTransactionAsync: (variables: SignTransactionVariables) => Promise<SignTransactionData>;
     reset: () => void;
     data: SignTransactionData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -193,7 +248,7 @@ declare const useTransferSTX: () => {
     transferSTXAsync: (variables: TransferSTXVariables) => Promise<string>;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -254,7 +309,7 @@ declare const useWriteContract: () => {
     writeContractAsync: WriteContractAsyncFn;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -295,4 +350,4 @@ declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
     contract: string;
 };
 
-export { type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };
+export { BaseError, type BaseErrorType, type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, UnsupportedMethodError, type UnsupportedMethodErrorType, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, WalletNotConnectedError, type WalletNotConnectedErrorType, WalletNotFoundError, type WalletNotFoundErrorType, WalletRequestError, type WalletRequestErrorType, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };

package/dist/index.d.ts

@@ -3,6 +3,61 @@ import { ClarityValue, TupleCV, PostCondition, PostConditionMode } from '@stacks
 import { ClarityAbi, ExtractAbiFunctionNames, Pretty, ExtractAbiFunction, ClarityAbiArgToPrimitiveTypeValue } from 'clarity-abitype';
 export { ClarityAbi } from 'clarity-abitype';
 
+type BaseErrorType = BaseError & {
+    name: 'StacksKitError';
+};
+declare class BaseError extends Error {
+    name: string;
+    shortMessage: string;
+    constructor(shortMessage: string, options?: {
+        cause?: Error;
+        details?: string;
+    });
+    walk(fn?: (err: unknown) => boolean): unknown;
+}
+type WalletNotConnectedErrorType = WalletNotConnectedError & {
+    name: 'WalletNotConnectedError';
+};
+declare class WalletNotConnectedError extends BaseError {
+    name: string;
+    constructor();
+}
+type WalletNotFoundErrorType = WalletNotFoundError & {
+    name: 'WalletNotFoundError';
+};
+declare class WalletNotFoundError extends BaseError {
+    name: string;
+    wallet: string;
+    constructor({ wallet }: {
+        wallet: string;
+    });
+}
+type UnsupportedMethodErrorType = UnsupportedMethodError & {
+    name: 'UnsupportedMethodError';
+};
+declare class UnsupportedMethodError extends BaseError {
+    name: string;
+    method: string;
+    wallet: string;
+    constructor({ method, wallet }: {
+        method: string;
+        wallet: string;
+    });
+}
+type WalletRequestErrorType = WalletRequestError & {
+    name: 'WalletRequestError';
+};
+declare class WalletRequestError extends BaseError {
+    name: string;
+    method: string;
+    wallet: string;
+    constructor({ method, wallet, cause }: {
+        method: string;
+        wallet: string;
+        cause: Error;
+    });
+}
+
 declare const SUPPORTED_STACKS_WALLETS: readonly ["xverse", "leather", "asigna", "fordefi", "wallet-connect", "okx"];
 type SupportedStacksWallet = (typeof SUPPORTED_STACKS_WALLETS)[number];
 
@@ -116,7 +171,7 @@ declare const useSignMessage: () => {
     signMessageAsync: (variables: SignMessageVariables) => Promise<SignMessageData>;
     reset: () => void;
     data: SignMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -142,7 +197,7 @@ declare const useSignStructuredMessage: () => {
     signStructuredMessageAsync: (variables: SignStructuredMessageVariables) => Promise<SignStructuredMessageData>;
     reset: () => void;
     data: SignStructuredMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -168,7 +223,7 @@ declare const useSignTransaction: () => {
     signTransactionAsync: (variables: SignTransactionVariables) => Promise<SignTransactionData>;
     reset: () => void;
     data: SignTransactionData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -193,7 +248,7 @@ declare const useTransferSTX: () => {
     transferSTXAsync: (variables: TransferSTXVariables) => Promise<string>;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -254,7 +309,7 @@ declare const useWriteContract: () => {
     writeContractAsync: WriteContractAsyncFn;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -295,4 +350,4 @@ declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
     contract: string;
 };
 
-export { type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };
+export { BaseError, type BaseErrorType, type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, UnsupportedMethodError, type UnsupportedMethodErrorType, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, WalletNotConnectedError, type WalletNotConnectedErrorType, WalletNotFoundError, type WalletNotFoundErrorType, WalletRequestError, type WalletRequestErrorType, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };

package/dist/index.js

@@ -4,6 +4,69 @@ import { jsx } from 'react/jsx-runtime';
 import { PostConditionMode, postConditionToHex, cvToHex, noneCV, contractPrincipalCV, standardPrincipalCV, boolCV, intCV, uintCV, bufferCV, stringAsciiCV, stringUtf8CV, someCV, listCV, tupleCV } from '@stacks/transactions';
 import { getPrimaryName } from 'bns-v2-sdk';
 
+// src/errors.ts
+var BaseError = class extends Error {
+  name = "StacksKitError";
+  shortMessage;
+  constructor(shortMessage, options) {
+    const message = [
+      shortMessage,
+      options?.details && `Details: ${options.details}`
+    ].filter(Boolean).join("\n\n");
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.shortMessage = shortMessage;
+  }
+  walk(fn) {
+    return walk(this, fn);
+  }
+};
+function walk(err, fn) {
+  if (fn?.(err)) return err;
+  if (err && typeof err === "object" && "cause" in err) {
+    return walk(err.cause, fn);
+  }
+  return err;
+}
+var WalletNotConnectedError = class extends BaseError {
+  name = "WalletNotConnectedError";
+  constructor() {
+    super("Wallet is not connected");
+  }
+};
+var WalletNotFoundError = class extends BaseError {
+  name = "WalletNotFoundError";
+  wallet;
+  constructor({ wallet }) {
+    super(`${wallet} wallet not found`, {
+      details: "The wallet extension may not be installed."
+    });
+    this.wallet = wallet;
+  }
+};
+var UnsupportedMethodError = class extends BaseError {
+  name = "UnsupportedMethodError";
+  method;
+  wallet;
+  constructor({ method, wallet }) {
+    super(`${method} is not supported by ${wallet} wallet`);
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+var WalletRequestError = class extends BaseError {
+  name = "WalletRequestError";
+  method;
+  wallet;
+  constructor({ method, wallet, cause }) {
+    super(`${wallet} wallet request failed`, {
+      cause,
+      details: cause.message
+    });
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+
 // src/constants/stacks-provider-mapping.ts
 var STACKS_TO_STACKS_CONNECT_PROVIDERS = {
   xverse: "XverseProviders.BitcoinProvider",
@@ -683,7 +746,7 @@ var useSignMessage = () => {
   const signMessageAsync = useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -692,7 +755,7 @@ var useSignMessage = () => {
         let result;
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           result = await window.okxwallet.stacks.signMessage({
             message: variables.message
@@ -709,7 +772,11 @@ var useSignMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -760,12 +827,13 @@ var useSignStructuredMessage = () => {
   const signStructuredMessageAsync = useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Structured message signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signStructuredMessage",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -779,7 +847,11 @@ var useSignStructuredMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signStructuredMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -835,12 +907,13 @@ var useSignTransaction = () => {
   const signTransactionAsync = useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Transaction signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signTransaction",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -856,7 +929,11 @@ var useSignTransaction = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signTransaction",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -918,7 +995,7 @@ var useTransferSTX = () => {
   const transferSTXAsync = useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -926,7 +1003,7 @@ var useTransferSTX = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             txType: "token_transfer",
@@ -961,7 +1038,11 @@ var useTransferSTX = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_transferStx",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1149,7 +1230,7 @@ var useWriteContract = () => {
   const writeContractAsync = useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -1158,7 +1239,7 @@ var useWriteContract = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             contractAddress: variables.address,
@@ -1193,7 +1274,11 @@ var useWriteContract = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_callContract",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1278,6 +1363,6 @@ function createContractConfig(config) {
   return config;
 }
 
-export { SUPPORTED_STACKS_WALLETS, StacksWalletProvider, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };
+export { BaseError, SUPPORTED_STACKS_WALLETS, StacksWalletProvider, UnsupportedMethodError, WalletNotConnectedError, WalletNotFoundError, WalletRequestError, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map