@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/core/analytics/instrumentation.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withMethodTracking = withMethodTracking;
+exports.withSyncMethodTracking = withSyncMethodTracking;
+exports.instrumentClass = instrumentClass;
+const chain_name_1 = require("./chain-name");
+const method_taxonomy_1 = require("./method-taxonomy");
+const sanitize_1 = require("./sanitize");
+const sentry_runtime_1 = require("./sentry-runtime");
+const sentry_1 = require("./sentry");
+/**
+ * Higher-order function to wrap SDK methods with performance tracking.
+ * Tracks method calls, timing, chain usage, and errors.
+ *
+ * @param methodName - Name of the method being wrapped
+ * @param method - The original async method
+ * @param getChainId - Function to get current chain ID
+ * @returns Wrapped method with tracking
+ */
+function withMethodTracking(methodName, method, getChainId) {
+    return async function trackedMethod(...args) {
+        if (!(0, sentry_1.isAnalyticsEnabled)()) {
+            return method(...args);
+        }
+        // Resolve the SDK before the sanitize/shape/category work — when
+        // @sentry/node fails to resolve, every call would otherwise pay the
+        // hot-path cost only to discard the result below.
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk) {
+            return method(...args);
+        }
+        const startTime = performance.now();
+        const chainId = getChainId?.();
+        const category = (0, method_taxonomy_1.getMethodCategory)(methodName);
+        const sanitizedArgs = (0, sanitize_1.sanitizeArgs)(args);
+        const argShape = (0, sanitize_1.computeArgShape)(args);
+        // Flipped the moment the wrapped method is invoked inside the span. The
+        // outer catch uses it to tell "Sentry's startSpan itself blew up before
+        // our method ran" (safe to fall back to a direct call) from "our method
+        // ran and threw" (must NOT be re-run — for a write method that would be
+        // a second broadcast of the same transaction).
+        let methodInvoked = false;
+        try {
+            // Use Sentry's startSpan for performance tracking (v8 API)
+            return await sdk.startSpan({
+                op: 'sdk.method',
+                name: methodName,
+                attributes: {
+                    // Scope tags only reach the root span in Sentry's span dataset;
+                    // child spans need the identity copied on as attributes or they
+                    // cannot be filtered by app or partner.
+                    ...(0, sentry_1.getSpanAttributes)(),
+                    chainId: chainId?.toString() || 'unknown',
+                    'sdk.chain': (0, chain_name_1.chainIdToTagValue)(chainId),
+                    'sdk.category': category,
+                    // Joined to a string because Sentry span attributes are scalar.
+                    'sdk.argShape': argShape.join('|'),
+                    ...sanitizedArgs,
+                },
+            }, async (span) => {
+                try {
+                    methodInvoked = true;
+                    const result = await method(...args);
+                    const duration = performance.now() - startTime;
+                    // Record success metrics
+                    span?.setAttribute('duration', Math.round(duration));
+                    span?.setAttribute('success', true);
+                    // Track method call
+                    trackMethodCall(methodName, {
+                        method: methodName,
+                        category,
+                        chainId,
+                        duration,
+                        success: true,
+                    }, { ...sanitizedArgs, argShape: argShape.join('|') });
+                    span?.setStatus({ code: 1 }); // OK status
+                    return result;
+                }
+                catch (error) {
+                    const duration = performance.now() - startTime;
+                    const errorType = error instanceof Error ? error.name : 'UnknownError';
+                    // Record error metrics
+                    span?.setAttribute('duration', Math.round(duration));
+                    span?.setAttribute('success', false);
+                    span?.setAttribute('error', error instanceof Error ? error.message : String(error));
+                    // Track failed method call
+                    trackMethodCall(methodName, {
+                        method: methodName,
+                        category,
+                        chainId,
+                        duration,
+                        success: false,
+                        errorType,
+                    }, { ...sanitizedArgs, argShape: argShape.join('|') });
+                    span?.setStatus({ code: 2, message: errorType }); // Error status
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            // If Sentry.startSpan fails BEFORE the method ran, fall back to a
+            // direct call so analytics never breaks SDK functionality. Once the
+            // method has been invoked, any error — even one whose message happens
+            // to mention "Sentry" — is the method's own and is re-thrown untouched.
+            if (!methodInvoked &&
+                error instanceof Error &&
+                error.message?.includes('Sentry')) {
+                return method(...args);
+            }
+            // Re-throw the original method error
+            throw error;
+        }
+    };
+}
+/**
+ * Track individual method calls as breadcrumbs and measurements.
+ */
+function trackMethodCall(methodName, metrics, args) {
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        // Add breadcrumb for method call
+        sdk.addBreadcrumb({
+            category: 'sdk.method',
+            message: methodName,
+            level: metrics.success ? 'info' : 'error',
+            data: {
+                chainId: metrics.chainId,
+                category: metrics.category,
+                duration: Math.round(metrics.duration),
+                errorType: metrics.errorType,
+                ...args,
+            },
+        });
+        // Set measurement for method duration
+        sdk.setMeasurement('sdk.method.duration', metrics.duration, 'millisecond');
+        // Counters: SUM(invocation) → total calls; SUM(error)/SUM(invocation) → error rate.
+        sdk.setMeasurement('sdk.method.invocation', 1, 'none');
+        sdk.setMeasurement('sdk.method.error', metrics.success ? 0 : 1, 'none');
+        // Only sticky-tag the last method name — useful for attributing errors that fire
+        // outside an active SDK span. sdk.category and sdk.chain are already recorded as
+        // span attributes on each call, so mutating the global scope with them here would
+        // just contaminate subsequent unrelated events with stale values.
+        sdk.setTag('sdk.last_method', methodName);
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
+/**
+ * Check if a function is async (returns a Promise).
+ */
+function isAsyncMethod(fn) {
+    // Check if constructor name indicates async
+    if (fn.constructor.name === 'AsyncFunction') {
+        return true;
+    }
+    // Check if function body suggests async
+    const fnString = fn.toString();
+    return fnString.includes('__awaiter') || fnString.startsWith('async');
+}
+/**
+ * Higher-order function to wrap synchronous SDK methods with tracking.
+ * Uses breadcrumbs for tracking since spans require async context.
+ *
+ * @param methodName - Name of the method being wrapped
+ * @param method - The original sync method
+ * @param getChainId - Function to get current chain ID
+ * @returns Wrapped method with tracking
+ */
+function withSyncMethodTracking(methodName, method, getChainId) {
+    return function trackedSyncMethod(...args) {
+        if (!(0, sentry_1.isAnalyticsEnabled)()) {
+            return method(...args);
+        }
+        // Same hot-path short-circuit as the async path.
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk) {
+            return method(...args);
+        }
+        const startTime = performance.now();
+        const chainId = getChainId?.();
+        const category = (0, method_taxonomy_1.getMethodCategory)(methodName);
+        const sanitizedArgs = (0, sanitize_1.sanitizeArgs)(args);
+        const argShape = (0, sanitize_1.computeArgShape)(args);
+        try {
+            const result = method(...args);
+            const duration = performance.now() - startTime;
+            // Track successful sync method call via breadcrumb
+            trackSyncMethodCall(methodName, {
+                method: methodName,
+                category,
+                chainId,
+                duration,
+                success: true,
+            }, { ...sanitizedArgs, argShape: argShape.join('|') });
+            return result;
+        }
+        catch (error) {
+            const duration = performance.now() - startTime;
+            const errorType = error instanceof Error ? error.name : 'UnknownError';
+            // Track failed sync method call
+            trackSyncMethodCall(methodName, {
+                method: methodName,
+                category,
+                chainId,
+                duration,
+                success: false,
+                errorType,
+            }, { ...sanitizedArgs, argShape: argShape.join('|') });
+            throw error;
+        }
+    };
+}
+/**
+ * Track synchronous method calls as breadcrumbs.
+ */
+function trackSyncMethodCall(methodName, metrics, args) {
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        // Add breadcrumb for sync method call
+        sdk.addBreadcrumb({
+            category: 'sdk.sync_method',
+            message: methodName,
+            level: metrics.success ? 'info' : 'error',
+            data: {
+                chainId: metrics.chainId,
+                category: metrics.category,
+                duration: Math.round(metrics.duration),
+                errorType: metrics.errorType,
+                ...args,
+            },
+        });
+        // Measurements omitted: sync methods have no span of their own, so setMeasurement
+        // would attach to whatever parent transaction happens to be active on the scope,
+        // overwriting its counters. The breadcrumb above already captures success/failure.
+        // `sdk.category` and `sdk.chain` stay off the global scope: concurrent sync
+        // calls would race on them and stamp stale values onto unrelated events (the
+        // breadcrumb above carries both per call). `sdk.last_chainId` stays because
+        // `isMutedChainEvent` in sentry.ts reads it to drop muted-chain events.
+        sdk.setTag('sdk.last_sync_method', methodName);
+        if (metrics.chainId !== undefined) {
+            sdk.setTag('sdk.last_chainId', metrics.chainId.toString());
+        }
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
+/**
+ * Instrument all methods on a class instance with tracking.
+ * This auto-wraps all public methods (both async and sync) without boilerplate.
+ *
+ * @param instance - The class instance to instrument
+ * @param getChainId - Function to get current chain ID
+ * @returns The same instance with instrumented methods
+ */
+function instrumentClass(instance, getChainId) {
+    try {
+        const proto = Object.getPrototypeOf(instance);
+        const methodNames = Object.getOwnPropertyNames(proto).filter((name) => {
+            // Skip constructor and private methods
+            if (name === 'constructor' || name.startsWith('_'))
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+            return typeof descriptor?.value === 'function';
+        });
+        for (const methodName of methodNames) {
+            const original = instance[methodName];
+            if (typeof original === 'function') {
+                if (isAsyncMethod(original)) {
+                    // Wrap async methods with span-based tracking
+                    instance[methodName] =
+                        withMethodTracking(methodName, original.bind(instance), getChainId);
+                }
+                else {
+                    // Wrap sync methods with breadcrumb-based tracking
+                    instance[methodName] =
+                        withSyncMethodTracking(methodName, original.bind(instance), getChainId);
+                }
+            }
+        }
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+    return instance;
+}
+//# sourceMappingURL=instrumentation.js.map

package/lib/core/analytics/method-taxonomy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical category for an SDK public method, used as the `sdk.category`
+ * Sentry tag so the partner-usage dashboard can roll calls up into
+ * `read.*` / `write.*` / `network` / `bridge` buckets.
+ */
+export type MethodCategory = 'read.vault' | 'read.position' | 'read.redemption' | 'read.price' | 'read.points' | 'read.subaccount' | 'read.staking' | 'read.layerzero' | 'read.solana' | 'read.stellar' | 'read.sui' | 'read.evm' | 'write.deposit' | 'write.redeem' | 'write.approve' | 'write.points' | 'write.stellar' | 'network' | 'bridge' | 'unknown';
+/**
+ * Map of public SDK method names to their {@link MethodCategory}.
+ *
+ * Keys are unqualified because `instrumentClass` walks the prototype and
+ * surfaces them that way; the same name on multiple adapters (e.g.
+ * `vaultDeposit` on EVM, Solana, Stellar) shares the same category.
+ */
+export declare const METHOD_CATEGORIES: Readonly<Record<string, MethodCategory>>;
+/**
+ * Look up the category for a method name, defaulting to `'unknown'` for
+ * methods not yet added to {@link METHOD_CATEGORIES}.
+ */
+export declare function getMethodCategory(methodName: string): MethodCategory;

package/lib/core/analytics/method-taxonomy.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METHOD_CATEGORIES = void 0;
+exports.getMethodCategory = getMethodCategory;
+/**
+ * Map of public SDK method names to their {@link MethodCategory}.
+ *
+ * Keys are unqualified because `instrumentClass` walks the prototype and
+ * surfaces them that way; the same name on multiple adapters (e.g.
+ * `vaultDeposit` on EVM, Solana, Stellar) shares the same category.
+ */
+exports.METHOD_CATEGORIES = {
+    getVault: 'read.vault',
+    getVaults: 'read.vault',
+    getTotalDeposited: 'read.vault',
+    getVaultLoans: 'read.vault',
+    getVaultSubaccountLoans: 'read.vault',
+    getVaultAllocations: 'read.vault',
+    getVaultApy: 'read.vault',
+    getVaultAnnualizedApy: 'read.vault',
+    getVaultTvl: 'read.vault',
+    getVaultHistoricalTimeseries: 'read.vault',
+    getVaultSummary: 'read.vault',
+    getVaultPnl: 'read.vault',
+    getVaultUnrealizedPnlHistory: 'read.vault',
+    getLatestUnrealizedPnl: 'read.vault',
+    getDashboardLoans: 'read.vault',
+    getDiscountFactors: 'read.vault',
+    getCollateralExcessOrDeficit: 'read.vault',
+    simulateCollateral: 'read.vault',
+    getRevertReason: 'read.vault',
+    getOtcPositions: 'read.vault',
+    getOtcMarginRequirements: 'read.vault',
+    getCuratorVaultSubaccounts: 'read.vault',
+    getCuratorVaultWhitelist: 'read.vault',
+    getTimelockRequests: 'read.vault',
+    getVaultPerformanceFees: 'read.vault',
+    getVaultOracleClassification: 'read.vault',
+    // Transparency dashboard (one per card/tab)
+    getVaultPositionSnapshot: 'read.vault',
+    getVaultBackingSeries: 'read.vault',
+    getVaultSmoothedApy: 'read.vault',
+    getVaultHistoricalAllocations: 'read.vault',
+    getVaultFeeConfig: 'read.vault',
+    getVaultGovernanceRoles: 'read.vault',
+    getVaultGovernancePermissions: 'read.vault',
+    getVaultGovernanceTimelocks: 'read.vault',
+    getVaultGovernanceAuditLog: 'read.vault',
+    getVaultBorrowerHealthFactor: 'read.vault',
+    getYieldLastRealizedOn: 'read.vault',
+    getVaultActivity: 'read.vault',
+    getSwapRouterDepositResult: 'read.vault',
+    getSwapRouterWhitelistedTokens: 'read.vault',
+    getSwapRouterEligibleVaults: 'read.vault',
+    getOriginInfo: 'read.vault',
+    getDepositRoute: 'read.vault',
+    getVaultPositions: 'read.position',
+    getVaultUserHistory: 'read.position',
+    getUserHistory: 'read.position',
+    getVaultUserTransfers: 'read.position',
+    getUserTransfers: 'read.position',
+    getVaultUserLifetimePnl: 'read.position',
+    getVaultAvailableRedemptions: 'read.redemption',
+    getVaultRedemptionHistory: 'read.redemption',
+    getVaultPendingRedemptions: 'read.redemption',
+    getVaultWithdrawals: 'read.redemption',
+    getWithdrawalRequestsWithStatus: 'read.redemption',
+    previewRedemption: 'read.redemption',
+    previewRwaRedemption: 'read.redemption',
+    getBurnableAmountByReceiver: 'read.redemption',
+    getRequirementByDate: 'read.redemption',
+    getScheduledTransactionsByDate: 'read.redemption',
+    getPrice: 'read.price',
+    getUserPoints: 'read.points',
+    fetchPointsLeaderboard: 'read.points',
+    getAllSubaccounts: 'read.subaccount',
+    getSubaccountHealthFactor: 'read.subaccount',
+    getSubaccountLoans: 'read.subaccount',
+    getSubaccountCefiPositions: 'read.subaccount',
+    getSubaccountOtcPositions: 'read.subaccount',
+    getSubaccountSummary: 'read.subaccount',
+    getSubaccountTransactions: 'read.subaccount',
+    getSubaccountLoanByAddress: 'read.subaccount',
+    getSubaccountDebank: 'read.subaccount',
+    getStakingPositions: 'read.staking',
+    getVaultStakingPositions: 'read.staking',
+    getLayerZeroDeposits: 'read.layerzero',
+    getLayerZeroRedeems: 'read.layerzero',
+    getVaultState: 'read.solana',
+    getVaultStateReadOnly: 'read.solana',
+    getToken: 'read.solana',
+    getTokenSymbol: 'read.solana',
+    fetchUserTokenBalance: 'read.solana',
+    fetchUserShareBalance: 'read.solana',
+    fetchUserShareBalanceRaw: 'read.solana',
+    // Both are offline resolvers (no RPC) — classified so the partner dashboard
+    // sees program-targeting calls instead of dropping them into 'unknown'.
+    getProgram: 'read.solana',
+    getProgramId: 'read.solana',
+    setWalletProvider: 'network',
+    // submitTransaction broadcasts a signed Soroban tx — it mutates on-chain
+    // state and belongs in the write bucket even though Stellar adapter call
+    // shape mirrors the read helpers (returns a hash, takes signed XDR).
+    submitTransaction: 'write.stellar',
+    getUserPosition: 'read.stellar',
+    // convertToShares is a read-only Soroban simulation despite its mutative-
+    // sounding name — runs through queryContract, no broadcast.
+    convertToShares: 'read.stellar',
+    // Offline helpers on the public adapter surface, classified under the
+    // chain's read bucket like getProgram/getProgramId above rather than
+    // leaking into 'unknown'.
+    isStellarAddress: 'read.stellar',
+    getExplorerLink: 'read.stellar',
+    isSuiAddress: 'read.sui',
+    isSuiVault: 'read.sui',
+    vaultAllowance: 'read.evm',
+    sendersWhitelistAddress: 'read.evm',
+    isWhitelisted: 'read.evm',
+    getDeposited: 'read.evm',
+    getRemainingAllocations: 'read.evm',
+    previewDeposit: 'read.vault',
+    previewRedeem: 'read.redemption',
+    allowance: 'read.evm',
+    balanceOf: 'read.evm',
+    maxDeposit: 'read.vault',
+    getIdleLiquidity: 'read.vault',
+    lagDuration: 'read.vault',
+    getWithdrawalEpoch: 'read.vault',
+    vaultDeposit: 'write.deposit',
+    depositNative: 'write.deposit',
+    swapAndDeposit: 'write.deposit',
+    depositViaSwapRouter: 'write.deposit',
+    depositNativeViaSwapRouter: 'write.deposit',
+    swapRouterDeposit: 'write.deposit',
+    vaultRedeem: 'write.redeem',
+    claimWithdrawal: 'write.redeem',
+    vaultRequestRedeem: 'write.redeem',
+    // Solana withdrawal queue: cancelling a request is part of the redeem flow.
+    vaultCancelRedeemRequest: 'write.redeem',
+    rwaRedeemAsset: 'write.redeem',
+    vaultApprove: 'write.approve',
+    approve: 'write.approve',
+    registerUserForPoints: 'write.points',
+    switchNetwork: 'network',
+    updateWallet: 'network',
+    clearWallet: 'network',
+    setSigner: 'network',
+};
+/**
+ * Look up the category for a method name, defaulting to `'unknown'` for
+ * methods not yet added to {@link METHOD_CATEGORIES}.
+ */
+function getMethodCategory(methodName) {
+    return exports.METHOD_CATEGORIES[methodName] ?? 'unknown';
+}
+//# sourceMappingURL=method-taxonomy.js.map

package/lib/core/analytics/metrics.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Track API response times and status.
+ *
+ * @param endpoint - The API endpoint called
+ * @param method - HTTP method used
+ * @param startTime - Start timestamp from performance.now()
+ * @param status - HTTP response status code (0 for network errors)
+ * @param server - Server identifier (production, staging, etc.)
+ */
+export declare function trackApiCall(endpoint: string, method: string, startTime: number, status: number, server: string): void;
+/**
+ * Track chain/network switches for usage distribution analysis.
+ *
+ * @param chainId - The chain ID being switched to
+ */
+export declare function trackNetworkSwitch(chainId: number): void;
+/**
+ * Track the outcome of an API-key verification check (e.g. `verifyUpshiftKey`).
+ * Records success/failure as a breadcrumb and a low-cardinality tag so
+ * verification failures are visible in the dashboard without leaking the key
+ * itself — callers must never pass the raw key value.
+ *
+ * @param keyType - Which key was verified (e.g. `'upshift'`)
+ * @param success - Whether the key was accepted
+ */
+export declare function trackKeyVerification(keyType: string, success: boolean): void;
+declare let cacheStats: {
+    hits: number;
+    misses: number;
+    sets: number;
+};
+/**
+ * Cache statistics snapshot. The SDK never recorded cache hits, misses, or
+ * sets, so every field is always `0`.
+ *
+ * @deprecated Always returns zeros. Kept only for API compatibility and will
+ * be removed in the next major release; there is no replacement.
+ */
+export declare function getCacheStats(): typeof cacheStats;
+/**
+ * Reset the cache statistics snapshot to zeros. The SDK never records any, so
+ * this has no observable effect.
+ *
+ * @deprecated Has no effect. Kept only for API compatibility and will be
+ * removed in the next major release; there is no replacement.
+ */
+export declare function resetCacheStats(): void;
+export {};

package/lib/core/analytics/metrics.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackApiCall = trackApiCall;
+exports.trackNetworkSwitch = trackNetworkSwitch;
+exports.trackKeyVerification = trackKeyVerification;
+exports.getCacheStats = getCacheStats;
+exports.resetCacheStats = resetCacheStats;
+const chain_name_1 = require("./chain-name");
+const sentry_runtime_1 = require("./sentry-runtime");
+const sentry_1 = require("./sentry");
+/**
+ * Track API response times and status.
+ *
+ * @param endpoint - The API endpoint called
+ * @param method - HTTP method used
+ * @param startTime - Start timestamp from performance.now()
+ * @param status - HTTP response status code (0 for network errors)
+ * @param server - Server identifier (production, staging, etc.)
+ */
+function trackApiCall(endpoint, method, startTime, status, server) {
+    if (!(0, sentry_1.isAnalyticsEnabled)())
+        return;
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        const duration = performance.now() - startTime;
+        // Normalize endpoint for aggregation (replace dynamic segments)
+        const normalizedEndpoint = normalizeEndpoint(endpoint);
+        // Add breadcrumb
+        sdk.addBreadcrumb({
+            category: 'api',
+            message: `${method} ${normalizedEndpoint}`,
+            level: status >= 400 || status === 0 ? 'error' : 'info',
+            data: {
+                endpoint: normalizedEndpoint,
+                method,
+                duration: Math.round(duration),
+                status,
+                server,
+            },
+        });
+        sdk.setMeasurement('api.duration', duration, 'millisecond');
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
+/**
+ * Track chain/network switches for usage distribution analysis.
+ *
+ * @param chainId - The chain ID being switched to
+ */
+function trackNetworkSwitch(chainId) {
+    if (!(0, sentry_1.isAnalyticsEnabled)())
+        return;
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        const chainLabel = (0, chain_name_1.chainIdToTagValue)(chainId);
+        sdk.addBreadcrumb({
+            category: 'network',
+            message: `Switched to chain ${chainId} (${chainLabel})`,
+            level: 'info',
+            data: { chainId, chain: chainLabel },
+        });
+        sdk.setTag('sdk.chain', chainLabel);
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
+/**
+ * Track the outcome of an API-key verification check (e.g. `verifyUpshiftKey`).
+ * Records success/failure as a breadcrumb and a low-cardinality tag so
+ * verification failures are visible in the dashboard without leaking the key
+ * itself — callers must never pass the raw key value.
+ *
+ * @param keyType - Which key was verified (e.g. `'upshift'`)
+ * @param success - Whether the key was accepted
+ */
+function trackKeyVerification(keyType, success) {
+    if (!(0, sentry_1.isAnalyticsEnabled)())
+        return;
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        sdk.addBreadcrumb({
+            category: 'auth.verify',
+            message: `${keyType} key verification ${success ? 'succeeded' : 'failed'}`,
+            level: success ? 'info' : 'warning',
+            data: { keyType, success },
+        });
+        sdk.setTag('auth.last_verified_key_type', keyType);
+        sdk.setTag('auth.last_verification_result', success ? 'success' : 'failure');
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
+/**
+ * Normalize endpoint URLs for aggregation.
+ * Replaces dynamic segments (addresses, IDs) with placeholders.
+ *
+ * @param endpoint - Raw endpoint URL
+ * @returns Normalized endpoint pattern
+ */
+function normalizeEndpoint(endpoint) {
+    return (endpoint
+        // Replace Ethereum addresses (0x + 40 hex chars)
+        .replace(/0x[a-fA-F0-9]{40}/g, ':address')
+        // Replace chain IDs (5+ digit numbers)
+        .replace(/\/\d{5,}/g, '/:chainId')
+        // Replace UUIDs
+        .replace(/[a-f0-9-]{36}/gi, ':uuid')
+        // Replace numeric IDs in paths
+        .replace(/\/\d+(?=\/|$)/g, '/:id'));
+}
+let cacheStats = { hits: 0, misses: 0, sets: 0 };
+/**
+ * Cache statistics snapshot. The SDK never recorded cache hits, misses, or
+ * sets, so every field is always `0`.
+ *
+ * @deprecated Always returns zeros. Kept only for API compatibility and will
+ * be removed in the next major release; there is no replacement.
+ */
+function getCacheStats() {
+    return { ...cacheStats };
+}
+/**
+ * Reset the cache statistics snapshot to zeros. The SDK never records any, so
+ * this has no observable effect.
+ *
+ * @deprecated Has no effect. Kept only for API compatibility and will be
+ * removed in the next major release; there is no replacement.
+ */
+function resetCacheStats() {
+    cacheStats = { hits: 0, misses: 0, sets: 0 };
+}
+//# sourceMappingURL=metrics.js.map