@circle-fin/app-kit 1.10.0 → 1.11.0

package/unifiedBalance.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
@@ -41,6 +52,27 @@ import { getAddress } from '@ethersproject/address';
  * }
  * ```
  */ 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.
  *
@@ -7080,13 +7112,12 @@ const swapTokenEnumSchema = 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;
@@ -8358,6 +8389,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 && {
@@ -8428,18 +8460,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
@@ -8652,7 +8681,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.
@@ -8668,7 +8697,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
@@ -8684,6 +8715,9 @@ function parseOrThrow(value, schema, context) {
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
@@ -8745,7 +8779,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};
@@ -20423,7 +20457,11 @@ const removeFundParamsSchema = 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
@@ -20460,7 +20498,10 @@ const removeFundParamsSchema = 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
@@ -20549,13 +20590,18 @@ const removeFundParamsSchema = 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
@@ -20776,7 +20822,11 @@ const removeFundParamsSchema = 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.
@@ -20790,7 +20840,12 @@ const removeFundParamsSchema = 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.
@@ -20917,6 +20972,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'
@@ -21128,7 +21188,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.
@@ -21147,11 +21212,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