@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/core/analytics/env.js

@@ -1,9 +1,17 @@
 "use strict";
+/**
+ * Environment-variable gates for analytics. Pure functions — safe to import
+ * anywhere, no Sentry side effects. Tested directly in `analytics.test.js`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readEnv = readEnv;
 exports.isAnalyticsForcedOnViaEnv = isAnalyticsForcedOnViaEnv;
 exports.isAnalyticsDisabledViaEnv = isAnalyticsDisabledViaEnv;
 exports.isNodeDevOrTestEnv = isNodeDevOrTestEnv;
+/**
+ * Read a process env var without crashing in browsers or in bundles where
+ * `process.env` is a frozen / proxied object that throws on missing keys.
+ */
 function readEnv(name) {
     try {
         if (typeof process !== 'undefined' && process.env) {
@@ -11,6 +19,7 @@ function readEnv(name) {
         }
     }
     catch {
+        // Bundlers occasionally throw on `process.env` access. Treat as unset.
     }
     return undefined;
 }
@@ -20,12 +29,29 @@ function isTruthyEnv(value) {
     const v = value.toLowerCase();
     return v === '1' || v === 'true' || v === 'yes' || v === 'on';
 }
+/**
+ * `AUGUST_SDK_FORCE_ANALYTICS=1` bypasses the dev/test and localhost gates.
+ * Used by our own smoke-test script and by partners deliberately exercising
+ * telemetry in a non-prod environment.
+ */
 function isAnalyticsForcedOnViaEnv() {
     return isTruthyEnv(readEnv('AUGUST_SDK_FORCE_ANALYTICS'));
 }
+/**
+ * `AUGUST_SDK_DISABLE_ANALYTICS=1` is the env equivalent of passing
+ * `analytics: { enabled: false }`. Useful when partners can't easily plumb
+ * config through (CI runners, ops scripts).
+ */
 function isAnalyticsDisabledViaEnv() {
     return isTruthyEnv(readEnv('AUGUST_SDK_DISABLE_ANALYTICS'));
 }
+/**
+ * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
+ * analytics in these environments so partners' local dev runs and Jest suites
+ * don't pollute the production Sentry project.
+ *
+ * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
+ */
 function isNodeDevOrTestEnv() {
     const env = readEnv('NODE_ENV');
     return env === 'development' || env === 'test';

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

@@ -1,3 +1,29 @@
+/**
+ * Analytics module for SDK usage tracking via Sentry.
+ *
+ * Features:
+ * - User identification (API key hash, wallet, fingerprint, session)
+ * - Method call tracking with timing
+ * - Cache hit/miss rate monitoring
+ * - API response time tracking
+ * - Chain/network usage distribution
+ *
+ * @example
+ * ```typescript
+ * // Analytics enabled by default
+ * const sdk = new AugustSDK({
+ *   providers: { 1: 'https://...' },
+ *   keys: { august: '...' },
+ * });
+ *
+ * // Opt-out of analytics
+ * const sdk = new AugustSDK({
+ *   providers: { 1: 'https://...' },
+ *   keys: { august: '...' },
+ *   analytics: { enabled: false },
+ * });
+ * ```
+ */
 export type { IAnalyticsConfig, IUserIdentity, IMethodCallMetrics, } from './types';
 export { hashApiKey, getSessionId, generateFingerprint, createUserIdentity, getUserId, } from './user-identity';
 export { initializeSentry, updateUser, clearUser, isAnalyticsEnabled, getSentry, resetAnalytics, captureSdkException, } from './sentry';

package/lib/core/analytics/index.js

@@ -1,12 +1,40 @@
 "use strict";
+/**
+ * Analytics module for SDK usage tracking via Sentry.
+ *
+ * Features:
+ * - User identification (API key hash, wallet, fingerprint, session)
+ * - Method call tracking with timing
+ * - Cache hit/miss rate monitoring
+ * - API response time tracking
+ * - Chain/network usage distribution
+ *
+ * @example
+ * ```typescript
+ * // Analytics enabled by default
+ * const sdk = new AugustSDK({
+ *   providers: { 1: 'https://...' },
+ *   keys: { august: '...' },
+ * });
+ *
+ * // Opt-out of analytics
+ * const sdk = new AugustSDK({
+ *   providers: { 1: 'https://...' },
+ *   keys: { august: '...' },
+ *   analytics: { enabled: false },
+ * });
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chainIdToTagValue = exports.getMethodCategory = exports.METHOD_CATEGORIES = exports.instrumentClass = exports.withSyncMethodTracking = exports.withMethodTracking = exports.computeArgShape = exports.sanitizeObject = exports.sanitizeArgs = exports.resetCacheStats = exports.getCacheStats = exports.trackNetworkSwitch = exports.trackApiCall = exports.isNodeDevOrTestEnv = exports.isAnalyticsForcedOnViaEnv = exports.isAnalyticsDisabledViaEnv = exports.readEnv = exports.getSentryRuntime = exports.getSentrySDK = exports.captureSdkException = exports.resetAnalytics = exports.getSentry = exports.isAnalyticsEnabled = exports.clearUser = exports.updateUser = exports.initializeSentry = exports.getUserId = exports.createUserIdentity = exports.generateFingerprint = exports.getSessionId = exports.hashApiKey = void 0;
+// User identity utilities
 var user_identity_1 = require("./user-identity");
 Object.defineProperty(exports, "hashApiKey", { enumerable: true, get: function () { return user_identity_1.hashApiKey; } });
 Object.defineProperty(exports, "getSessionId", { enumerable: true, get: function () { return user_identity_1.getSessionId; } });
 Object.defineProperty(exports, "generateFingerprint", { enumerable: true, get: function () { return user_identity_1.generateFingerprint; } });
 Object.defineProperty(exports, "createUserIdentity", { enumerable: true, get: function () { return user_identity_1.createUserIdentity; } });
 Object.defineProperty(exports, "getUserId", { enumerable: true, get: function () { return user_identity_1.getUserId; } });
+// Sentry core
 var sentry_1 = require("./sentry");
 Object.defineProperty(exports, "initializeSentry", { enumerable: true, get: function () { return sentry_1.initializeSentry; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return sentry_1.updateUser; } });
@@ -15,30 +43,37 @@ Object.defineProperty(exports, "isAnalyticsEnabled", { enumerable: true, get: fu
 Object.defineProperty(exports, "getSentry", { enumerable: true, get: function () { return sentry_1.getSentry; } });
 Object.defineProperty(exports, "resetAnalytics", { enumerable: true, get: function () { return sentry_1.resetAnalytics; } });
 Object.defineProperty(exports, "captureSdkException", { enumerable: true, get: function () { return sentry_1.captureSdkException; } });
+// Isomorphic Sentry runtime resolver
 var sentry_runtime_1 = require("./sentry-runtime");
 Object.defineProperty(exports, "getSentrySDK", { enumerable: true, get: function () { return sentry_runtime_1.getSentrySDK; } });
 Object.defineProperty(exports, "getSentryRuntime", { enumerable: true, get: function () { return sentry_runtime_1.getSentryRuntime; } });
+// Env-variable gates
 var env_1 = require("./env");
 Object.defineProperty(exports, "readEnv", { enumerable: true, get: function () { return env_1.readEnv; } });
 Object.defineProperty(exports, "isAnalyticsDisabledViaEnv", { enumerable: true, get: function () { return env_1.isAnalyticsDisabledViaEnv; } });
 Object.defineProperty(exports, "isAnalyticsForcedOnViaEnv", { enumerable: true, get: function () { return env_1.isAnalyticsForcedOnViaEnv; } });
 Object.defineProperty(exports, "isNodeDevOrTestEnv", { enumerable: true, get: function () { return env_1.isNodeDevOrTestEnv; } });
+// Metrics tracking
 var metrics_1 = require("./metrics");
 Object.defineProperty(exports, "trackApiCall", { enumerable: true, get: function () { return metrics_1.trackApiCall; } });
 Object.defineProperty(exports, "trackNetworkSwitch", { enumerable: true, get: function () { return metrics_1.trackNetworkSwitch; } });
 Object.defineProperty(exports, "getCacheStats", { enumerable: true, get: function () { return metrics_1.getCacheStats; } });
 Object.defineProperty(exports, "resetCacheStats", { enumerable: true, get: function () { return metrics_1.resetCacheStats; } });
+// Sanitization utilities
 var sanitize_1 = require("./sanitize");
 Object.defineProperty(exports, "sanitizeArgs", { enumerable: true, get: function () { return sanitize_1.sanitizeArgs; } });
 Object.defineProperty(exports, "sanitizeObject", { enumerable: true, get: function () { return sanitize_1.sanitizeObject; } });
 Object.defineProperty(exports, "computeArgShape", { enumerable: true, get: function () { return sanitize_1.computeArgShape; } });
+// Method instrumentation
 var instrumentation_1 = require("./instrumentation");
 Object.defineProperty(exports, "withMethodTracking", { enumerable: true, get: function () { return instrumentation_1.withMethodTracking; } });
 Object.defineProperty(exports, "withSyncMethodTracking", { enumerable: true, get: function () { return instrumentation_1.withSyncMethodTracking; } });
 Object.defineProperty(exports, "instrumentClass", { enumerable: true, get: function () { return instrumentation_1.instrumentClass; } });
+// Method taxonomy
 var method_taxonomy_1 = require("./method-taxonomy");
 Object.defineProperty(exports, "METHOD_CATEGORIES", { enumerable: true, get: function () { return method_taxonomy_1.METHOD_CATEGORIES; } });
 Object.defineProperty(exports, "getMethodCategory", { enumerable: true, get: function () { return method_taxonomy_1.getMethodCategory; } });
+// Chain name helper
 var chain_name_1 = require("./chain-name");
 Object.defineProperty(exports, "chainIdToTagValue", { enumerable: true, get: function () { return chain_name_1.chainIdToTagValue; } });
 //# sourceMappingURL=index.js.map

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

@@ -1,3 +1,29 @@
+/**
+ * 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
+ */
 export declare function withMethodTracking<T extends (...args: unknown[]) => Promise<unknown>>(methodName: string, method: T, getChainId?: () => number | undefined): T;
+/**
+ * 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
+ */
 export declare function withSyncMethodTracking<T extends (...args: unknown[]) => unknown>(methodName: string, method: T, getChainId?: () => number | undefined): T;
+/**
+ * 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
+ */
 export declare function instrumentClass<T extends object>(instance: T, getChainId: () => number | undefined): T;

package/lib/core/analytics/instrumentation.js

@@ -8,11 +8,23 @@ 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);
@@ -23,6 +35,7 @@ function withMethodTracking(methodName, method, getChainId) {
         const sanitizedArgs = (0, sanitize_1.sanitizeArgs)(args);
         const argShape = (0, sanitize_1.computeArgShape)(args);
         try {
+            // Use Sentry's startSpan for performance tracking (v8 API)
             return await sdk.startSpan({
                 op: 'sdk.method',
                 name: methodName,
@@ -30,6 +43,7 @@ function withMethodTracking(methodName, method, getChainId) {
                     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,
                 },
@@ -37,8 +51,10 @@ function withMethodTracking(methodName, method, getChainId) {
                 try {
                     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,
@@ -46,15 +62,17 @@ function withMethodTracking(methodName, method, getChainId) {
                         duration,
                         success: true,
                     }, { ...sanitizedArgs, argShape: argShape.join('|') });
-                    span?.setStatus({ code: 1 });
+                    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,
@@ -63,24 +81,31 @@ function withMethodTracking(methodName, method, getChainId) {
                         success: false,
                         errorType,
                     }, { ...sanitizedArgs, argShape: argShape.join('|') });
-                    span?.setStatus({ code: 2, message: errorType });
+                    span?.setStatus({ code: 2, message: errorType }); // Error status
                     throw error;
                 }
             });
         }
         catch (error) {
+            // If Sentry.startSpan fails, fall back to direct method call
+            // This ensures analytics never breaks SDK functionality
             if (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,
@@ -93,9 +118,12 @@ function trackMethodCall(methodName, metrics, args) {
                 ...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');
+        // Update tags for filtering
         sdk.setTag('sdk.last_method', methodName);
         if (metrics.category) {
             sdk.setTag('sdk.category', metrics.category);
@@ -106,20 +134,36 @@ function trackMethodCall(methodName, metrics, args) {
         }
     }
     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);
@@ -132,6 +176,7 @@ function withSyncMethodTracking(methodName, method, getChainId) {
         try {
             const result = method(...args);
             const duration = performance.now() - startTime;
+            // Track successful sync method call via breadcrumb
             trackSyncMethodCall(methodName, {
                 method: methodName,
                 category,
@@ -144,6 +189,7 @@ function withSyncMethodTracking(methodName, method, getChainId) {
         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,
@@ -156,11 +202,15 @@ function withSyncMethodTracking(methodName, method, getChainId) {
         }
     };
 }
+/**
+ * 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,
@@ -173,6 +223,7 @@ function trackSyncMethodCall(methodName, metrics, args) {
                 ...args,
             },
         });
+        // Counters — sync calls attach to whatever span is active on the scope.
         sdk.setMeasurement('sdk.method.invocation', 1, 'none');
         sdk.setMeasurement('sdk.method.error', metrics.success ? 0 : 1, 'none');
         sdk.setTag('sdk.last_sync_method', methodName);
@@ -185,12 +236,22 @@ function trackSyncMethodCall(methodName, metrics, args) {
         }
     }
     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);
@@ -200,10 +261,12 @@ function instrumentClass(instance, getChainId) {
             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);
                 }
@@ -211,6 +274,7 @@ function instrumentClass(instance, getChainId) {
         }
     }
     catch {
+        // Silently fail - analytics should never break SDK
     }
     return instance;
 }

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

@@ -1,3 +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

@@ -2,6 +2,13 @@
 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',
@@ -15,6 +22,8 @@ exports.METHOD_CATEGORIES = {
     getVaultHistoricalTimeseries: 'read.vault',
     getVaultSummary: 'read.vault',
     getVaultPnl: 'read.vault',
+    getVaultUnrealizedPnlHistory: 'read.vault',
+    getLatestUnrealizedPnl: 'read.vault',
     getVaultBorrowerHealthFactor: 'read.vault',
     getYieldLastRealizedOn: 'read.vault',
     getVaultPositions: 'read.position',
@@ -48,8 +57,13 @@ exports.METHOD_CATEGORIES = {
     fetchUserTokenBalance: 'read.solana',
     fetchUserShareBalance: 'read.solana',
     fetchUserShareBalanceRaw: 'read.solana',
+    // 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',
     getEmberVaults: 'read.sui',
     getEmberTVL: 'read.sui',
@@ -79,6 +93,10 @@ exports.METHOD_CATEGORIES = {
     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';
 }

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

@@ -1,10 +1,33 @@
+/**
+ * Aggregated cache statistics for monitoring.
+ */
 declare let cacheStats: {
     hits: number;
     misses: number;
     sets: number;
 };
+/**
+ * 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;
+/**
+ * Get current cache statistics.
+ */
 export declare function getCacheStats(): typeof cacheStats;
+/**
+ * Reset cache statistics (useful for testing).
+ */
 export declare function resetCacheStats(): void;
 export {};

package/lib/core/analytics/metrics.js

@@ -7,11 +7,23 @@ exports.resetCacheStats = resetCacheStats;
 const chain_name_1 = require("./chain-name");
 const sentry_runtime_1 = require("./sentry-runtime");
 const sentry_1 = require("./sentry");
+/**
+ * Aggregated cache statistics for monitoring.
+ */
 let cacheStats = {
     hits: 0,
     misses: 0,
     sets: 0,
 };
+/**
+ * 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;
@@ -20,7 +32,9 @@ function trackApiCall(endpoint, method, startTime, status, server) {
         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}`,
@@ -33,13 +47,21 @@ function trackApiCall(endpoint, method, startTime, status, server) {
                 server,
             },
         });
+        // Set measurement for performance tracking
         sdk.setMeasurement('api.duration', duration, 'millisecond');
+        // Update tags for filtering
         sdk.setTag('api.last_endpoint', normalizedEndpoint);
         sdk.setTag('api.server', server);
     }
     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;
@@ -58,18 +80,36 @@ function trackNetworkSwitch(chainId) {
         sdk.setTag('sdk.chain', chainLabel);
     }
     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'));
 }
+/**
+ * Get current cache statistics.
+ */
 function getCacheStats() {
     return { ...cacheStats };
 }
+/**
+ * Reset cache statistics (useful for testing).
+ */
 function resetCacheStats() {
     cacheStats = { hits: 0, misses: 0, sets: 0 };
 }

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

@@ -1,6 +1,44 @@
+/**
+ * Redact secrets from a free-form string (error messages, URLs, log lines).
+ *
+ * @example
+ *   sanitizeString('Request failed: https://api.example.com/v1?api_key=abc123')
+ *   // → 'Request failed: https://api.example.com/v1?api_key=[REDACTED]'
+ */
 export declare function sanitizeString(input: string): string;
+/**
+ * Return a redacted clone of `err`. Preserves prototype (so `instanceof` checks
+ * keep working), `name`, all own properties (`code`, `status`, `correlationId`,
+ * …), and `cause`. Subclass constructors are NOT invoked — they may have
+ * positional signatures (`new AugustAuthError(code, message, opts)`) that would
+ * misalign if we naively passed the sanitized message as the first arg.
+ */
 export declare function sanitizeError(err: unknown): unknown;
+/** Sanitize arbitrary log input (strings, errors, objects, arrays, primitives). */
 export declare function sanitizeForLogging(input: unknown, depth?: number): unknown;
+/**
+ * Compute a value-free structural signature for a list of arguments — used
+ * as the `sdk.argShape` Sentry tag so dashboards can count which overload of
+ * a method partners call without ingesting wallet addresses or other PII.
+ *
+ * Tokens: primitives keep their `typeof` name; 0x-prefixed strings narrow to
+ * `'address'` / `'tx-hash'` / `'hex'`; arrays render as `'array(<length>)'`;
+ * objects render as `'options{<sorted,keys>}'`, capped at 12 keys.
+ *
+ * @param args - The `arguments` array of an instrumented method.
+ * @returns Shape tokens, one per arg, in argument order.
+ *
+ * @example
+ *   computeArgShape(['0xabc…ef', { vault: '0x…', chainId: 1 }])
+ *   // → ['address', 'options{chainId,vault}']
+ */
 export declare function computeArgShape(args: unknown[]): string[];
+/**
+ * Sanitize method arguments for safe logging to Sentry.
+ * Removes sensitive data and truncates large values.
+ */
 export declare function sanitizeArgs(args: unknown[]): Record<string, unknown>;
+/**
+ * Recursively sanitize an object, removing sensitive keys.
+ */
 export declare function sanitizeObject(obj: Record<string, unknown>, depth?: number): Record<string, unknown>;