@circle-fin/app-kit 1.10.0 → 1.11.0

package/estimateSwap.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 'pino';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
@@ -44,6 +55,51 @@ import { keccak256 } from '@ethersproject/keccak256';
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Check whether the current runtime exposes a browser DOM.
+ *
+ * @remarks
+ * This intentionally does not treat every non-Node runtime as a browser.
+ * Server-side edge runtimes such as Cloudflare Workers, Deno, and Supabase
+ * Edge Functions do not expose Node globals but can safely use server
+ * credentials. A Node.js runtime remains server-side even when a test or SSR
+ * environment provides a DOM shim.
+ *
+ * @returns `true` when running in a browser window, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isBrowserEnvironment } from '@core/utils'
+ *
+ * if (isBrowserEnvironment()) {
+ *   throw new Error('Server-only secrets must not be used in the browser')
+ * }
+ * ```
+ */ const isBrowserEnvironment = ()=>{
+    const browserWindow = globalThis.window;
+    return !isNodeEnvironment() && browserWindow?.document !== undefined;
+};
+/**
+ * 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.
  *
@@ -8021,13 +8077,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG$1.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;
@@ -9528,6 +9583,7 @@ const swapTokenEnumSchema = z.enum([
     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 && {
@@ -9598,18 +9654,15 @@ const swapTokenEnumSchema = z.enum([
         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
@@ -9777,7 +9830,7 @@ const swapTokenEnumSchema = z.enum([
         // 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.
@@ -9793,7 +9846,9 @@ const swapTokenEnumSchema = z.enum([
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -9809,9 +9864,45 @@ const swapTokenEnumSchema = z.enum([
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
+/**
+ * Emit telemetry for a completed operation without affecting its caller.
+ *
+ * No-ops when `config.disabled` is `true`. Like {@link withErrorTelemetry},
+ * failures while constructing or submitting the telemetry payload are reported
+ * as a soft warning and never change a completed operation's result.
+ *
+ * @param eventType - The telemetry event type for the completed operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain, token, and transaction context.
+ * @returns Nothing.
+ * @throws Never — telemetry failures are reported as warnings.
+ *
+ * @example
+ * ```typescript
+ * import { emitSuccessTelemetry } from '@core/utils'
+ *
+ * emitSuccessTelemetry(
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', destinationChain: 'Base', tokenIn: 'USDC' },
+ * )
+ * ```
+ */ function emitSuccessTelemetry(eventType, config, context) {
+    if (config.disabled) {
+        return;
+    }
+    try {
+        void emitAnalyticsLog(buildPayload(config, eventType, undefined, context));
+    } catch (telemetryError) {
+        warnTelemetryDrop(eventType, telemetryError);
+    }
+}
 /**
  * Wrap an async operation with error telemetry.
  *
@@ -9870,7 +9961,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.12.1";
+var version$2 = "1.12.2";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -10731,7 +10822,13 @@ var TransferSpeed;
 /**
  * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
  * hookData must start with.
- */ Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+ *
+ * Encoded with `TextEncoder` (a browser-safe Web API) rather than `Buffer.from`
+ * so this module-level constant does not reference the Node `Buffer` global at
+ * import time. App Kit inlines this provider into its bundle without a Buffer polyfill, and a
+ * bare `Buffer` here crashes browser bundles (e.g. Vite) on load — even for apps
+ * that never touch the prepaid FORWARD path. Mirrors `buildForwardingHookData`.
+ */ Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
 
 /**
  * The minimum finality threshold for CCTPv2 transfers.
@@ -10765,7 +10862,7 @@ var TransferSpeed;
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.4.0";
+var version$1 = "1.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -11598,6 +11695,16 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'estimatedAmount is required',
         invalid_type_error: 'estimatedAmount must be a string'
     }).min(1, 'estimatedAmount must be a non-empty string'),
+    // Per-swap join key echoed back verbatim on success telemetry. Optional so a
+    // not-yet-upgraded service (no field) still validates during rollout. A
+    // malformed/non-UUID value is coerced to `undefined` (no telemetry id) rather
+    // than throwing: this is a telemetry-only field (stripped from the developer
+    // result, never used for control flow), so it must not be able to abort the
+    // swap via `parseCreateSwapResponse().parse()`. Mirrors the best-effort,
+    // never-throw contract of the rest of the telemetry stack. Implemented with
+    // `preprocess` rather than Zod's `.catch()` because static analysis misreads
+    // `.catch` on the schema chain as an unhandled Promise (S7785).
+    correlationId: z.preprocess((value)=>z.string().uuid().safeParse(value).success ? value : undefined, z.string().optional()),
     config: createSwapRequestBaseSchema.shape.config.optional(),
     fees: createSwapFeesSchema.optional(),
     transaction: createSwapTransactionSchema
@@ -11684,6 +11791,45 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * }
  * ```
  */ const isGetTokenRatesResponse = (obj)=>getTokenRatesResponseSchema.safeParse(obj).success;
+/**
+ * Assert that a Stablecoin Service kit key is not being supplied from a browser.
+ *
+ * The kit key (`KIT_KEY:<id>:<secret>`) is a server-only secret. Every
+ * Stablecoin Service request that attaches an `Authorization: Bearer` header
+ * funnels through this package, so calling this guard before that header is
+ * built prevents the secret from being sent from — and thus bundled into — a
+ * client application. In Node.js the check is a no-op, preserving the
+ * legitimate "hold the kit key on the server, forward the prepared transaction
+ * to the client" flow. When no kit key is supplied the permissionless (keyless)
+ * client path remains fully allowed.
+ *
+ * @param apiKey - The inline kit key for the request, or `undefined` when none
+ *   was supplied (permissionless mode).
+ * @returns Nothing.
+ * @throws KitError with VALIDATION_FAILED when a kit key is supplied while
+ *   running in a browser environment. The secret value is never echoed.
+ *
+ * @example
+ * ```typescript
+ * import { assertBrowserSafeApiKey } from '@core/service-client'
+ *
+ * // Server (Node.js): no-op, request proceeds with the Authorization header.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser: throws to stop the secret from leaking into the client bundle.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser, permissionless: allowed.
+ * assertBrowserSafeApiKey(undefined)
+ * ```
+ */ const assertBrowserSafeApiKey = (apiKey)=>{
+    if (apiKey === undefined) {
+        return;
+    }
+    if (isBrowserEnvironment()) {
+        throw createValidationFailedError$1('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run kit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+    }
+};
 
 /**
  * Create a cross-chain bridge and swap transaction through the Stablecoin Service.
@@ -11741,6 +11887,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     const url = new URL('/v1/stablecoinKits/swap', STABLECOIN_SERVICE_BASE_URL).toString();
     // Remove the API key from the request body
     const { apiKey, ...requestBody } = validatedParams;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(apiKey);
     const effectiveConfig = {
         ...DEFAULT_CONFIG,
         headers: {
@@ -11895,6 +12043,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
     // Use validated data
     const validatedParams = result.data;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     // Build the API URL
     const url = buildQuoteUrl(validatedParams);
     // Merge default config with Authorization header
@@ -11967,6 +12117,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             toChain: result.data.toChain
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildSwapStatusUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG,
@@ -12071,6 +12223,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             addresses: result.data.addresses
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildTokenRatesUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG,
@@ -16497,6 +16651,11 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
                 apiKey: serviceParams.apiKey
             }
         });
+        // Per-swap correlation id returned by the service as a top-level response
+        // field for every chain (EVM + Solana). Attached to success telemetry so a
+        // swap can be correlated across records; never used for control flow.
+        // Undefined only against a not-yet-upgraded service that omits it.
+        const correlationId = serviceResponse.correlationId;
         // Build and return SwapResult
         return {
             tokenIn,
@@ -16506,6 +16665,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             fromAddress: serviceParams.fromAddress,
             toAddress: serviceParams.toAddress,
             txHash,
+            ...correlationId !== undefined && {
+                correlationId
+            },
             executedTransactions,
             ...config !== undefined && {
                 config
@@ -19405,7 +19567,13 @@ async function resolveTokenDecimals(context, resolvedParams) {
  *   amountIn: '50.00'
  * })
  * ```
- */ async function swap(context, params, /** @internal */ onBroadcast) {
+ */ async function swap(context, params, /**
+   * @internal
+   * Invoked after a successful broadcast with the on-chain `txHash` and the
+   * service-issued `correlationId` (join key for success telemetry). The
+   * service returns `correlationId` for every chain (EVM + Solana); it is
+   * undefined only against a not-yet-upgraded service that omits the field.
+   */ onBroadcast) {
     // Step 1: Validate parameters using schema
     assertSwapParams(params, swapParamsSchema);
     // Step 2: Resolve parameters (chain definitions, wallet addresses, token aliases preserved)
@@ -19425,13 +19593,16 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // Step 5: Execute swap via provider
     const swapParams = buildServiceSwapParams(resolvedParams, paramsWithFees);
     const providerResult = await provider.swap(swapParams);
+    // `correlationId` is an internal telemetry join key, not part of the public
+    // SwapResult — strip it here so it never leaks into the formatted result.
+    const { correlationId, ...providerResultPublic } = providerResult;
     // A throwing `onBroadcast` must never strand the caller after a
     // successful swap broadcast — the chain has moved. `safeInvokeCallback`
     // swallows the error and surfaces a `console.warn` prefixed with
     // `[stablecoin-kits swap-kit] callback threw and was swallowed:` so a
     // kit-side closure bug stays debuggable rather than vanishing.
     safeInvokeCallback('swap-kit', ()=>{
-        onBroadcast?.(providerResult.txHash);
+        onBroadcast?.(providerResultPublic.txHash, correlationId);
     });
     const { tokenInDecimals, tokenOutDecimals } = await resolveTokenDecimals(context, resolvedParams);
     // Step 6: Compose chain identity (owned by the kit, derived from the
@@ -19440,10 +19611,10 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // resolves `progress` — the provider's snapshot, or a terminal `'DONE'` for
     // a provider that omits it (a synchronous same-chain completion).
     const composedResult = {
-        ...providerResult,
+        ...providerResultPublic,
         chainIn: resolvedParams.from.chain,
         chainOut: resolvedParams.toChain ?? resolvedParams.from.chain,
-        progress: providerResult.progress ?? {
+        progress: providerResultPublic.progress ?? {
             status: 'DONE'
         }
     };
@@ -20296,7 +20467,13 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
  */ class SwapKit {
     context;
     /** Whether error telemetry is disabled. */ disableErrorReporting;
-    /** Per-kit telemetry identity for shared helpers. */ telemetryConfig;
+    /** Per-kit telemetry identity for error reporting. */ telemetryConfig;
+    /**
+   * Per-kit telemetry identity for success/analytics events. Gated by
+   * `disableAnalytics` (independent of `disableErrorReporting`) so a developer
+   * can opt out of volume analytics without also silencing error reports —
+   * mirrors EarnKit.
+   */ analyticsTelemetryConfig;
     /**
    * Create a new SwapKit instance.
    *
@@ -20350,6 +20527,11 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
             sdkVersion: pkg$1.version,
             disabled: this.disableErrorReporting
         };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg$1.version,
+            disabled: config.disableAnalytics === true
+        };
     }
     /**
    * Estimate the output amount and fees for a swap operation.
@@ -20390,8 +20572,12 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * console.log(`Fees:`, quote.fees)
    * ```
    */ async estimate(params) {
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
         return withErrorTelemetry(async ()=>estimate(this.context, params), SWAP_EVENT_TYPES.ESTIMATE, this.telemetryConfig, {
             sourceChain: resolveChainName(params.from.chain),
+            ...destinationChain != null && {
+                destinationChain
+            },
             tokenIn: params.tokenIn,
             tokenOut: params.tokenOut
         });
@@ -20450,16 +20636,54 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * ```
    */ async swap(params) {
         let txHash;
-        return withErrorTelemetry(async ()=>swap(this.context, params, (h)=>{
-                txHash = h;
-            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, ()=>({
+        let correlationId;
+        // Shared context builder so the error resolver and the success emit stay in
+        // lockstep — a field added here reaches both call sites. Reads the per-call
+        // locals lazily, so txHash/correlationId (set during the swap) are captured
+        // whenever it is invoked.
+        // Destination chain is the primary attribution dimension for cross-chain
+        // swaps; resolved once from the (static) params. Omitted for same-chain
+        // swaps that leave `to.chain` unset (destination == source).
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
+        const buildTelemetryContext = ()=>({
                 sourceChain: resolveChainName(params.from.chain),
+                ...destinationChain != null && {
+                    destinationChain
+                },
                 tokenIn: params.tokenIn,
                 tokenOut: params.tokenOut,
                 ...txHash != null && {
                     txHash
+                },
+                ...correlationId != null && {
+                    correlationId
                 }
-            }));
+            });
+        const result = await withErrorTelemetry(async ()=>swap(this.context, params, (h, cId)=>{
+                txHash = h;
+                correlationId = cId;
+            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, buildTelemetryContext);
+        // withErrorTelemetry only emits on failure. Record the successful swap here
+        // so the backend can attribute swap volume to a developer: the client event
+        // carries the (burn) txHash + correlationId, which joins to the
+        // server-emitted event carrying entity_id. Best-effort; never throws.
+        //
+        // Emit whenever a broadcast happened, i.e. we have the source/burn txHash.
+        // For a cross-chain swap that is the source-chain burn (progress is still
+        // PENDING while the destination mint settles) — we intentionally attribute
+        // at broadcast using the burn txHash rather than tracking the destination
+        // leg, which keeps the capture simple and self-contained in swap().
+        //
+        // Guard against a terminal-failure result: the EVM provider throws on
+        // revert today, but the kit is provider-agnostic, so a provider that
+        // returns a FAILED/NOT_FOUND result without throwing must not be recorded
+        // as a successful swap. Routed through analyticsTelemetryConfig so it is
+        // gated by disableAnalytics, independent of error reporting.
+        const status = result.progress?.status;
+        if (txHash != null && status !== 'FAILED' && status !== 'NOT_FOUND') {
+            emitSuccessTelemetry(SWAP_EVENT_TYPES.SWAP, this.analyticsTelemetryConfig, buildTelemetryContext());
+        }
+        return result;
     }
     /**
    * Fetch the current status of a swap from the Stablecoin Service.
@@ -20838,6 +21062,9 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
     const kit = new SwapKit({
         ...context.disableErrorReporting != null && {
             disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.disableAnalytics != null && {
+            disableAnalytics: context.disableAnalytics
         }
     });
     if (hasBoth) {
@@ -20899,7 +21126,7 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
 };
 
 var name = "@circle-fin/earn-kit";
-var version = "1.3.0";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -22363,6 +22590,8 @@ function hasCrossChainDepositQuoteShape(params) {
     config: earnConfigSchema.optional()
 });
 
+/** SDK name used in telemetry payloads. */ resolveKitSdkName(pkg.name);
+
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);