@circle-fin/app-kit 1.10.0 → 1.11.0

package/unifiedBalance.cjs

@@ -18,6 +18,17 @@
 
 'use strict';
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+const { Buffer } = require('buffer');
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 var zod = require('zod');
 var web3_js = require('@solana/web3.js');
 require('bn.js');
@@ -47,6 +58,27 @@ var bs58__default = /*#__PURE__*/_interopDefault(bs58);
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -7086,13 +7118,12 @@ const swapTokenEnumSchema = zod.z.enum([
         headers: {
             ...DEFAULT_CONFIG.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -8364,6 +8395,7 @@ function parseOrThrow(value, schema, context) {
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
         const errorDetails = {
             ...payload.errorDetails.errorCode !== undefined && {
@@ -8434,18 +8466,15 @@ function parseOrThrow(value, schema, context) {
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
             },
             body: JSON.stringify(toSafePayload(payload)),
             signal: controller.signal
@@ -8658,7 +8687,7 @@ function parseOrThrow(value, schema, context) {
         // discards the stack trace, nested `cause`, and any custom Error
         // properties — exactly the context an on-call needs when a
         // resolver-closure regression triggers this path.
-        console.warn(`[stablecoin-kits telemetry] dropped error event '${eventType}':`, cause);
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -8674,7 +8703,9 @@ function parseOrThrow(value, schema, context) {
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -8690,6 +8721,9 @@ function parseOrThrow(value, schema, context) {
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
@@ -8751,7 +8785,7 @@ function parseOrThrow(value, schema, context) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.3.0";
+var version = "1.3.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -20429,7 +20463,11 @@ const removeFundParamsSchema = zod.z.object({
 // Remove Fund Operations
 // ---------------------------------------------------------------------------
 /**
- * Kick off a delayed fund removal from an account.
+ * Kick off a delayed recovery fund removal from an account.
+ *
+ * Use `initiateRemoveFund` only as a trustless fallback when the normal spend
+ * flow is unavailable. For day-to-day movement out of a Unified Balance, use
+ * `spend`.
  *
  * Validates `from` and `amount`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -20466,7 +20504,10 @@ const removeFundParamsSchema = zod.z.object({
     return provider.initiateRemoveFund(resolved);
 }
 /**
- * Complete a fund removal once the 7-day activation period has passed.
+ * Complete a recovery fund removal once the 7-day withdrawal delay has passed.
+ *
+ * Use `removeFund` only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * Validates `from`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -20555,13 +20596,18 @@ const removeFundParamsSchema = zod.z.object({
 /** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg.name);
 /**
  * A high-level class-based interface for cross-chain USDC deposits,
- * spending, balance queries, delegation management, and withdrawals.
+ * spending, balance queries, delegation management, and recovery fund removals.
  *
  * UnifiedBalanceKit provides a familiar class-based API for developers who
  * prefer traditional object-oriented patterns. The class maintains an
  * internal context and provides methods that delegate to the standalone
  * operation functions exported by this package.
  *
+ * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+ * trustless recovery path for situations where the normal spend flow is
+ * unavailable, and it requires a 7-day withdrawal delay before funds can be
+ * removed.
+ *
  * @remarks
  * For functional usage, import and use the operations directly:
  * ```typescript
@@ -20782,7 +20828,11 @@ const removeFundParamsSchema = zod.z.object({
         });
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Kick off a delayed recovery fund removal from an account.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner's adapter context, amount, and
    *   optional token type.
@@ -20796,7 +20846,12 @@ const removeFundParamsSchema = zod.z.object({
         });
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a recovery fund removal once the 7-day withdrawal delay has
+   * passed.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner context matching the original
    *   fund removal initiation.
@@ -20923,6 +20978,11 @@ registerKit(`${pkg.name}/${pkg.version}`);
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -21134,7 +21194,12 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.removeDelegate(params);
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Initiate a trustless recovery removal from an account.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Calling this method starts the 7-day withdrawal delay before the removal can
+   * be completed.
    *
    * @param params - The account owner's adapter context, amount, and token.
    * @returns Promise resolving to the initiation details.
@@ -21153,11 +21218,16 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.initiateRemoveFund(params);
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a trustless recovery removal after the withdrawal delay.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Both EVM and Solana removals require a 7-day withdrawal delay after
+   * `initiateRemoveFund` before funds can be removed.
    *
    * @param params - The account owner context matching the original initiation.
    * @returns Promise resolving to the fund removal details.
-   * @throws {KitError} If the activation period has not elapsed or the
+   * @throws {KitError} If the withdrawal delay has not elapsed or the
    *   on-chain transaction fails.
    *
    * @example

package/unifiedBalance.d.cts

@@ -6977,10 +6977,13 @@ interface GetDelegateStatusParams<TAdapterCapabilities extends AdapterCapabiliti
 }
 
 /**
- * Parameters for initiating a delayed fund removal from a Gateway
+ * Parameters for initiating a delayed recovery fund removal from a Gateway
  * account.
  *
  * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
+ *
  * Fund removals have a mandatory 7-day delay before they can be
  * completed.  Only one removal may be pending per chain at a
  * time.  Initiating a second removal on the same chain adds the
@@ -7063,7 +7066,12 @@ interface InitiateRemoveFundResult {
     explorerUrl?: string;
 }
 /**
- * Parameters for completing a fund removal after the activation period.
+ * Parameters for completing a recovery fund removal after the withdrawal
+ * delay.
+ *
+ * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * @typeParam TAdapterCapabilities - Adapter capability constraints.
  * @typeParam TChainIdentifier - Accepted chain identifier type.
@@ -7160,6 +7168,11 @@ interface GetSupportedChainsOptions {
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -7361,7 +7374,12 @@ declare class AppKitUnifiedBalance {
      */
     removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>;
     /**
-     * Kick off a delayed fund removal from an account.
+     * Initiate a trustless recovery removal from an account.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Calling this method starts the 7-day withdrawal delay before the removal can
+     * be completed.
      *
      * @param params - The account owner's adapter context, amount, and token.
      * @returns Promise resolving to the initiation details.
@@ -7379,11 +7397,16 @@ declare class AppKitUnifiedBalance {
      */
     initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>;
     /**
-     * Complete a fund removal once the activation period has passed.
+     * Complete a trustless recovery removal after the withdrawal delay.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Both EVM and Solana removals require a 7-day withdrawal delay after
+     * `initiateRemoveFund` before funds can be removed.
      *
      * @param params - The account owner context matching the original initiation.
      * @returns Promise resolving to the fund removal details.
-     * @throws {KitError} If the activation period has not elapsed or the
+     * @throws {KitError} If the withdrawal delay has not elapsed or the
      *   on-chain transaction fails.
      *
      * @example

package/unifiedBalance.d.mts

@@ -6977,10 +6977,13 @@ interface GetDelegateStatusParams<TAdapterCapabilities extends AdapterCapabiliti
 }
 
 /**
- * Parameters for initiating a delayed fund removal from a Gateway
+ * Parameters for initiating a delayed recovery fund removal from a Gateway
  * account.
  *
  * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
+ *
  * Fund removals have a mandatory 7-day delay before they can be
  * completed.  Only one removal may be pending per chain at a
  * time.  Initiating a second removal on the same chain adds the
@@ -7063,7 +7066,12 @@ interface InitiateRemoveFundResult {
     explorerUrl?: string;
 }
 /**
- * Parameters for completing a fund removal after the activation period.
+ * Parameters for completing a recovery fund removal after the withdrawal
+ * delay.
+ *
+ * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * @typeParam TAdapterCapabilities - Adapter capability constraints.
  * @typeParam TChainIdentifier - Accepted chain identifier type.
@@ -7160,6 +7168,11 @@ interface GetSupportedChainsOptions {
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -7361,7 +7374,12 @@ declare class AppKitUnifiedBalance {
      */
     removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>;
     /**
-     * Kick off a delayed fund removal from an account.
+     * Initiate a trustless recovery removal from an account.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Calling this method starts the 7-day withdrawal delay before the removal can
+     * be completed.
      *
      * @param params - The account owner's adapter context, amount, and token.
      * @returns Promise resolving to the initiation details.
@@ -7379,11 +7397,16 @@ declare class AppKitUnifiedBalance {
      */
     initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>;
     /**
-     * Complete a fund removal once the activation period has passed.
+     * Complete a trustless recovery removal after the withdrawal delay.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Both EVM and Solana removals require a 7-day withdrawal delay after
+     * `initiateRemoveFund` before funds can be removed.
      *
      * @param params - The account owner context matching the original initiation.
      * @returns Promise resolving to the fund removal details.
-     * @throws {KitError} If the activation period has not elapsed or the
+     * @throws {KitError} If the withdrawal delay has not elapsed or the
      *   on-chain transaction fails.
      *
      * @example

package/unifiedBalance.d.ts

@@ -6977,10 +6977,13 @@ interface GetDelegateStatusParams<TAdapterCapabilities extends AdapterCapabiliti
 }
 
 /**
- * Parameters for initiating a delayed fund removal from a Gateway
+ * Parameters for initiating a delayed recovery fund removal from a Gateway
  * account.
  *
  * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
+ *
  * Fund removals have a mandatory 7-day delay before they can be
  * completed.  Only one removal may be pending per chain at a
  * time.  Initiating a second removal on the same chain adds the
@@ -7063,7 +7066,12 @@ interface InitiateRemoveFundResult {
     explorerUrl?: string;
 }
 /**
- * Parameters for completing a fund removal after the activation period.
+ * Parameters for completing a recovery fund removal after the withdrawal
+ * delay.
+ *
+ * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * @typeParam TAdapterCapabilities - Adapter capability constraints.
  * @typeParam TChainIdentifier - Accepted chain identifier type.
@@ -7160,6 +7168,11 @@ interface GetSupportedChainsOptions {
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -7361,7 +7374,12 @@ declare class AppKitUnifiedBalance {
      */
     removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>;
     /**
-     * Kick off a delayed fund removal from an account.
+     * Initiate a trustless recovery removal from an account.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Calling this method starts the 7-day withdrawal delay before the removal can
+     * be completed.
      *
      * @param params - The account owner's adapter context, amount, and token.
      * @returns Promise resolving to the initiation details.
@@ -7379,11 +7397,16 @@ declare class AppKitUnifiedBalance {
      */
     initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>;
     /**
-     * Complete a fund removal once the activation period has passed.
+     * Complete a trustless recovery removal after the withdrawal delay.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Both EVM and Solana removals require a 7-day withdrawal delay after
+     * `initiateRemoveFund` before funds can be removed.
      *
      * @param params - The account owner context matching the original initiation.
      * @returns Promise resolving to the fund removal details.
-     * @throws {KitError} If the activation period has not elapsed or the
+     * @throws {KitError} If the withdrawal delay has not elapsed or the
      *   on-chain transaction fails.
      *
      * @example