@circle-fin/bridge-kit 1.0.0 → 1.1.0

package/index.d.ts

@@ -19,7 +19,7 @@
 import { Abi } from 'abitype';
 import { TransactionInstruction, Signer } from '@solana/web3.js';
 import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2';
-import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-private/node_modules/zod/dist/types/index.d.ts';
+import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-private/kits/bridge-kit/node_modules/zod/dist/types/index.d.ts';
 
 /**
  * @packageDocumentation
@@ -410,6 +410,7 @@ declare enum Blockchain {
     Algorand_Testnet = "Algorand_Testnet",
     Aptos = "Aptos",
     Aptos_Testnet = "Aptos_Testnet",
+    Arc_Testnet = "Arc_Testnet",
     Arbitrum = "Arbitrum",
     Arbitrum_Sepolia = "Arbitrum_Sepolia",
     Avalanche = "Avalanche",
@@ -2349,6 +2350,24 @@ declare class Actionable<AllActions> {
     dispatch<K extends keyof AllActions>(action: K, payload: AllActions[K]): void;
 }
 
+/**
+ * Set an application-level identifier prefix for all HTTP requests.
+ *
+ * This allows applications to identify themselves in the user agent string,
+ * which is useful for tracking and analytics at the application level.
+ *
+ * @param prefix - Application identifier with version, e.g., "my-app/1.0.0"
+ *
+ * @example
+ * ```typescript
+ * import { setExternalPrefix } from '\@circle-fin/bridge-kit'
+ *
+ * setExternalPrefix('my-dapp/2.1.0')
+ * // All subsequent HTTP requests will include this prefix
+ * ```
+ */
+declare const setExternalPrefix: (prefix: string) => void;
+
 /**
  * Transfer speed options for cross-chain operations.
  *
@@ -2572,7 +2591,26 @@ interface BridgeConfig {
     /**
      * The maximum fee to pay for the burn operation.
      *
-     * @defaultValue 0
+     * Provide the amount as a base-10 numeric string representing the
+     * token amount in human-readable format. For example: to set a maximum
+     * fee of 1 USDC, pass `"1"`. Decimal values are supported (e.g., `"0.5"`
+     * for half a USDC).
+     *
+     * @defaultValue `"0"`
+     *
+     * @example
+     * ```typescript
+     * import type { BridgeConfig, TransferSpeed } from '@core/provider'
+     *
+     * const config: BridgeConfig = {
+     *   transferSpeed: TransferSpeed.FAST,
+     *   maxFee: "1", // 1 USDC maximum fee
+     *   customFee: {
+     *     value: "0.5", // 0.5 USDC developer fee
+     *     recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
+     *   }
+     * }
+     * ```
      */
     maxFee?: string;
     /**
@@ -2583,8 +2621,8 @@ interface BridgeConfig {
 /**
  * Custom fee configuration charged by the integrator.
  *
- * Use to charge an absolute fee on the source chain, in the token's
- * smallest unit.
+ * Use to charge an absolute fee on the source chain in human-readable
+ * token amounts.
  *
  * @remarks
  * This is an absolute amount, not a percentage. The `recipientAddress` must be
@@ -2595,7 +2633,7 @@ interface BridgeConfig {
  * import type { CustomFee } from '@core/provider'
  *
  * const config: CustomFee = {
- *   value: '1000000', // 1 USDC in base units (6 decimals)
+ *   value: '1', // 1 USDC
  *   recipientAddress: '0x1234567890123456789012345678901234567890',
  * }
  * ```
@@ -2603,20 +2641,25 @@ interface BridgeConfig {
 interface CustomFee {
     /**
      * The absolute fee to charge for the transfer.
-     * Provide the amount as a base-10 numeric string representing the integer amount of the token (not in smallest units).
-     * For example: to charge 1 USDC or 1 USDC, pass `'1'`.
+     *
+     * Provide the amount as a base-10 numeric string representing the token
+     * amount in human-readable format. For example: to charge 1 USDC, pass
+     * `"1"`. Decimal values are supported (e.g., `"0.5"` for half a USDC).
      * This is not a percentage.
      *
-     * Note: passing `'0'` results in no fee being charged.
+     * Note: passing `"0"` results in no fee being charged.
      */
     value?: string | undefined;
     /**
      * The fee recipient for the bridge transfer.
-     * This is the address that will receive the fee on the source chain of the bridge transfer.
-     * The fee recipient address **must be a valid address for the source chain** of the bridge transfer.
+     *
+     * This is the address that will receive the fee on the source chain of the
+     * bridge transfer. The fee recipient address **must be a valid address for
+     * the source chain** of the bridge transfer.
      *
      * For example: if bridging from Ethereum to Solana, pass an EVM address like
-     * `'0x1234567890123456789012345678901234567890'` because the source chain is Ethereum.
+     * `"0x1234567890123456789012345678901234567890"` because the source chain
+     * is Ethereum.
      */
     recipientAddress?: string | undefined;
 }
@@ -3732,13 +3775,15 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
-    }, "strip", z.ZodTypeAny, {
+        address: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
             waitForTransaction: (...args: unknown[]) => unknown;
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3746,6 +3791,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }>;
     to: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
         adapter: z.ZodObject<{
@@ -3762,6 +3808,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
+        address: z.ZodOptional<z.ZodString>;
     } & {
         recipientAddress: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -3772,6 +3819,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3780,6 +3828,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }>, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3788,6 +3837,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3796,6 +3846,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     }>, z.ZodObject<{
         adapter: z.ZodObject<{
             prepare: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
@@ -3811,6 +3862,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         }>;
         chain: never;
+        address: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3818,6 +3870,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }, {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3825,12 +3878,13 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     }>]>;
     amount: z.ZodPipeline<z.ZodString, z.ZodType<string, z.ZodTypeDef, string>>;
     token: z.ZodOptional<z.ZodLiteral<"USDC">>;
     config: z.ZodOptional<z.ZodObject<{
         transferSpeed: z.ZodOptional<z.ZodNativeEnum<typeof TransferSpeed>>;
-        maxFee: z.ZodOptional<z.ZodString>;
+        maxFee: z.ZodOptional<z.ZodPipeline<z.ZodString, z.ZodType<string, z.ZodTypeDef, string>>>;
         customFee: z.ZodOptional<z.ZodObject<{
             value: z.ZodOptional<z.ZodType<string, z.ZodTypeDef, string>>;
             recipientAddress: z.ZodOptional<z.ZodString>;
@@ -3864,6 +3918,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     };
     to: {
         adapter: {
@@ -3872,6 +3927,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     } | {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3880,6 +3936,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     };
     amount: string;
     token?: "USDC" | undefined;
@@ -3899,6 +3956,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     };
     to: {
         adapter: {
@@ -3907,6 +3965,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
             getAddress: (...args: unknown[]) => unknown;
         };
         chain: never;
+        address?: string | undefined;
     } | {
         adapter: {
             prepare: (...args: unknown[]) => unknown;
@@ -3915,6 +3974,7 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
         };
         chain: never;
         recipientAddress: string;
+        address?: string | undefined;
     };
     amount: string;
     token?: "USDC" | undefined;
@@ -4044,5 +4104,164 @@ declare class KitError extends Error implements ErrorDetails {
     constructor(details: ErrorDetails);
 }
 
-export { Blockchain, BridgeKit, KitError, bridgeParamsWithChainIdentifierSchema };
+/**
+ * Type guard to check if an error is a KitError instance.
+ *
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { isKitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
+ * }
+ * ```
+ */
+declare function isKitError(error: unknown): error is KitError;
+/**
+ * Checks if an error is a KitError with FATAL recoverability.
+ *
+ * FATAL errors indicate issues that cannot be resolved through retries,
+ * such as invalid inputs, configuration problems, or business rule
+ * violations. These errors require user intervention to fix.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is a KitError with FATAL recoverability
+ *
+ * @example
+ * ```typescript
+ * import { isFatalError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isFatalError(error)) {
+ *     // Show user-friendly error message - don't retry
+ *     showUserError(error.message)
+ *   }
+ * }
+ * ```
+ */
+declare function isFatalError(error: unknown): boolean;
+/**
+ * Checks if an error is a KitError with RETRYABLE recoverability.
+ *
+ * RETRYABLE errors indicate transient failures that may succeed on
+ * subsequent attempts, such as network timeouts or temporary service
+ * unavailability. These errors are safe to retry after a delay.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is a KitError with RETRYABLE recoverability
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Implement retry logic with exponential backoff
+ *     setTimeout(() => retryOperation(), 5000)
+ *   }
+ * }
+ * ```
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * Combined type guard to check if error is KitError with INPUT type.
+ *
+ * INPUT errors have error codes in the 1000-1099 range and represent
+ * validation failures, invalid parameters, or user input problems.
+ * These errors are always FATAL and require the user to correct their
+ * input before retrying.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with INPUT error code range
+ *
+ * @example
+ * ```typescript
+ * import { isInputError } from '@core/errors'
+ * import { createBridgeKit } from '@core/bridge'
+ *
+ * async function handleBridge() {
+ *   const kit = createBridgeKit(config)
+ *   const params = { amount: '100', from: 'ethereum', to: 'polygon' }
+ *
+ *   try {
+ *     await kit.bridge(params)
+ *   } catch (error) {
+ *     if (isInputError(error)) {
+ *       console.log(`Input error: ${error.message} (code: ${error.code})`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isInputError(error: unknown): error is KitError;
+/**
+ * Safely extracts error message from any error type.
+ *
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
+ *
+ * @example
+ * ```typescript
+ * import { getErrorMessage } from '@core/errors'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Gets the error code from a KitError, or null if not applicable.
+ *
+ * This utility safely extracts the numeric error code from KitError
+ * instances, returning null for non-KitError types. Useful for
+ * programmatic error handling based on specific error codes.
+ *
+ * @param error - Unknown error to extract code from
+ * @returns Error code number, or null if not a KitError
+ *
+ * @example
+ * ```typescript
+ * import { getErrorCode, InputError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   const code = getErrorCode(error)
+ *   if (code === InputError.NETWORK_MISMATCH.code) {
+ *     // Handle network mismatch specifically
+ *     showNetworkMismatchHelp()
+ *   }
+ * }
+ * ```
+ */
+declare function getErrorCode(error: unknown): number | null;
+
+export { Blockchain, BridgeKit, KitError, bridgeParamsWithChainIdentifierSchema, getErrorCode, getErrorMessage, isFatalError, isInputError, isKitError, isRetryableError, setExternalPrefix };
 export type { ActionHandler, BridgeKitConfig, BridgeParams, BridgeResult, ChainDefinition, ChainIdentifier, ErrorDetails, Recoverability };