@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/core/analytics/sanitize.js

@@ -6,6 +6,7 @@ exports.sanitizeForLogging = sanitizeForLogging;
 exports.computeArgShape = computeArgShape;
 exports.sanitizeArgs = sanitizeArgs;
 exports.sanitizeObject = sanitizeObject;
+/** Keys that should never be sent to logging/observability sinks */
 const SENSITIVE_KEYS = [
     'apikey',
     'api_key',
@@ -25,6 +26,7 @@ const SENSITIVE_KEYS = [
     'mnemonic',
     'seed',
 ];
+/** Regex patterns applied in order to scrub secrets from free-form strings. */
 const STRING_REDACTION_PATTERNS = [
     [/(authorization\s*[:=]\s*)(bearer|basic|token)\s+\S+/gi, '$1$2 [REDACTED]'],
     [
@@ -34,11 +36,19 @@ const STRING_REDACTION_PATTERNS = [
     [/(gateway\.thegraph\.com\/api\/)[A-Za-z0-9]{20,}(\/)/g, '$1[REDACTED]$2'],
     [/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED_JWT]'],
     [/\bnpm_[A-Za-z0-9]{30,}\b/g, '[REDACTED_NPM_TOKEN]'],
+    // Stop value match at & # so adjacent query params aren't swallowed.
     [
         /(\b(?:api[-_]?key|apikey|password|secret|private[-_]?key|mnemonic|seed)\s*[:=]\s*)["']?[^\s"',;}&#]+["']?/gi,
         '$1[REDACTED]',
     ],
 ];
+/**
+ * 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]'
+ */
 function sanitizeString(input) {
     if (!input)
         return input;
@@ -48,6 +58,13 @@ function sanitizeString(input) {
     }
     return out;
 }
+/**
+ * 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.
+ */
 function sanitizeError(err) {
     if (!(err instanceof Error))
         return err;
@@ -73,6 +90,7 @@ function sanitizeError(err) {
     safe.name = err.name;
     return safe;
 }
+/** Sanitize arbitrary log input (strings, errors, objects, arrays, primitives). */
 function sanitizeForLogging(input, depth = 0) {
     if (input === null || input === undefined)
         return input;
@@ -92,6 +110,22 @@ function sanitizeForLogging(input, depth = 0) {
     }
     return `[${typeof input}]`;
 }
+/**
+ * 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}']
+ */
 function computeArgShape(args) {
     return args.map((arg) => shapeOf(arg));
 }
@@ -125,6 +159,10 @@ function shapeOf(value) {
     }
     return t;
 }
+/**
+ * Sanitize method arguments for safe logging to Sentry.
+ * Removes sensitive data and truncates large values.
+ */
 function sanitizeArgs(args) {
     const sanitized = {};
     args.forEach((arg, index) => {
@@ -134,6 +172,7 @@ function sanitizeArgs(args) {
             return;
         }
         if (typeof arg === 'string') {
+            // Truncate long strings
             sanitized[key] = arg.length > 100 ? `${arg.substring(0, 100)}...` : arg;
             return;
         }
@@ -145,16 +184,22 @@ function sanitizeArgs(args) {
             sanitized[key] = sanitizeObject(arg);
             return;
         }
+        // For functions or other types, just note the type
         sanitized[key] = `[${typeof arg}]`;
     });
     return sanitized;
 }
+/**
+ * Recursively sanitize an object, removing sensitive keys.
+ */
 function sanitizeObject(obj, depth = 0) {
+    // Prevent deep recursion
     if (depth > 3) {
         return { _truncated: true };
     }
     const sanitized = {};
     for (const [key, value] of Object.entries(obj)) {
+        // Skip sensitive keys
         if (SENSITIVE_KEYS.some((sk) => key.toLowerCase().includes(sk.toLowerCase()))) {
             sanitized[key] = '[REDACTED]';
             continue;
@@ -164,6 +209,7 @@ function sanitizeObject(obj, depth = 0) {
             continue;
         }
         if (typeof value === 'string') {
+            // Check if value looks like a private key or sensitive data
             if (value.length > 64 && /^[a-fA-F0-9]+$/.test(value)) {
                 sanitized[key] = '[REDACTED_HEX]';
                 continue;

package/lib/core/analytics/sentry-runtime.d.ts

@@ -1,4 +1,15 @@
 import type * as SentryBrowser from '@sentry/browser';
+/**
+ * Returns the resolved Sentry SDK for the current runtime, or `null` if no
+ * SDK can be loaded. Idempotent and cached.
+ */
 export declare function getSentrySDK(): typeof SentryBrowser | null;
+/**
+ * Returns the detected runtime label (`'browser'` | `'node'` | `'unknown'`).
+ * Used to set the `sdk.runtime` Sentry tag.
+ */
 export declare function getSentryRuntime(): 'browser' | 'node' | 'unknown';
+/**
+ * Reset the cached SDK reference and runtime detection. Test-only.
+ */
 export declare function resetSentryRuntime(): void;

package/lib/core/analytics/sentry-runtime.js

@@ -19,11 +19,17 @@ function detectRuntime() {
         }
     }
     catch {
+        // Property access on locked-down globals can throw in some sandboxes.
     }
     return 'unknown';
 }
 function getNodeRequire() {
     try {
+        // `new Function` is opaque to bundler static analysis (keeps
+        // @sentry/node out of browser bundles) AND blocked by strict
+        // script-src CSPs without 'unsafe-eval'. The CSP-blocked path falls
+        // through to @sentry/browser — do NOT replace with a direct
+        // `require('@sentry/node')`, which breaks the browser bundle.
         const req = new Function('return typeof require === "function" ? require : null')();
         return typeof req === 'function' ? req : null;
     }
@@ -43,6 +49,8 @@ function loadSentrySDK() {
                 return cachedSdk;
             }
             catch (err) {
+                // Fall through to @sentry/browser, but surface it — running on Node
+                // without @sentry/node loses process-level exception capture.
                 logger_1.Logger.log.warn('analytics.runtime.sentry-node-missing', {
                     error: err instanceof Error ? err.message : String(err),
                     hint: 'Add @sentry/node to your dependencies for full Node telemetry coverage.',
@@ -62,15 +70,26 @@ function loadSentrySDK() {
     }
     return cachedSdk;
 }
+/**
+ * Returns the resolved Sentry SDK for the current runtime, or `null` if no
+ * SDK can be loaded. Idempotent and cached.
+ */
 function getSentrySDK() {
     return loadSentrySDK();
 }
+/**
+ * Returns the detected runtime label (`'browser'` | `'node'` | `'unknown'`).
+ * Used to set the `sdk.runtime` Sentry tag.
+ */
 function getSentryRuntime() {
     if (detectedRuntime === 'unknown') {
         detectedRuntime = detectRuntime();
     }
     return detectedRuntime;
 }
+/**
+ * Reset the cached SDK reference and runtime detection. Test-only.
+ */
 function resetSentryRuntime() {
     cachedSdk = null;
     detectedRuntime = 'unknown';

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

@@ -1,12 +1,57 @@
 import type * as Sentry from '@sentry/browser';
 import { IEnv } from '../../types';
 import { IAnalyticsConfig } from './types';
+/**
+ * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
+ * only refresh user identity and the cached API-key hash.
+ *
+ * @param config - Analytics configuration. Pass `tracesSampleRate` to
+ *   override the Phase 1/2 default of `1.0`.
+ * @param environment - Current environment (DEV or PROD).
+ * @param walletAddress - Optional wallet address for user identification.
+ * @param apiKey - Optional API key (hashed for identification).
+ * @param appName - Optional app-name slug. Set as the global `app.name`
+ *   tag on every event; falls back to `'unverified:anonymous'` when
+ *   omitted.
+ */
 export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
+/**
+ * Update the current user identity in Sentry.
+ * Called when wallet address changes.
+ *
+ * @param walletAddress - New wallet address (or undefined to clear)
+ * @param environment - Current environment
+ */
 export declare function updateUser(walletAddress?: string, environment?: IEnv): void;
+/**
+ * Clear wallet from user identity.
+ * Called when user disconnects wallet.
+ */
 export declare function clearUser(): void;
+/**
+ * Check if analytics is enabled and initialized.
+ */
 export declare function isAnalyticsEnabled(): boolean;
+/**
+ * Get the current Sentry instance for advanced usage.
+ * Returns null if analytics is disabled.
+ */
 export declare function getSentry(): typeof Sentry | null;
+/**
+ * Reset analytics state (useful for testing).
+ */
 export declare function resetAnalytics(): void;
+/**
+ * Capture an exception into Sentry with SDK-specific context. Use from
+ * top-level error handlers (CLI, middleware, unhandled rejections) to
+ * report failures that don't flow through the auto-instrumented method
+ * surface. No-ops when analytics is disabled.
+ *
+ * @param error - Thrown value. Non-Error values are wrapped.
+ * @param options - `surface` ('cli' | 'sdk' | 'react' | string), extra `tags`,
+ *   `extra` data, and a `flushTimeoutMs` to await before resolving (needed
+ *   in Node when the process is about to exit).
+ */
 export declare function captureSdkException(error: unknown, options?: {
     surface?: 'cli' | 'sdk' | 'react' | string;
     tags?: Record<string, string>;

package/lib/core/analytics/sentry.js

@@ -12,18 +12,31 @@ const constants_1 = require("./constants");
 const env_1 = require("./env");
 const sentry_runtime_1 = require("./sentry-runtime");
 const user_identity_1 = require("./user-identity");
+/** Track initialization state */
 let isInitialized = false;
+/** Track if analytics is enabled */
 let isEnabled = true;
+/** Current user identity */
 let currentIdentity = null;
+/** Cached API key for identity updates */
 let cachedApiKey;
+/**
+ * Get the SDK version from the generated version file.
+ * Falls back to 'development' if file doesn't exist (during local dev).
+ */
 function getSDKVersion() {
     try {
+        // version.ts is generated at publish time and gitignored
         return require('./version').SDK_VERSION || 'development';
     }
     catch {
+        // version.ts doesn't exist in dev - use fallback
         return 'development';
     }
 }
+/**
+ * Check if running on localhost.
+ */
 function isLocalhost() {
     try {
         if (typeof window !== 'undefined' && window.location) {
@@ -37,25 +50,44 @@ function isLocalhost() {
         }
     }
     catch {
+        // Silently fail
     }
     return false;
 }
+/**
+ * Safely set a Sentry tag. Silently fails on error.
+ */
 function safeSetTag(key, value) {
     try {
         const sdk = (0, sentry_runtime_1.getSentrySDK)();
         sdk?.setTag(key, value);
     }
     catch {
+        // Silently fail - analytics should never break SDK
     }
 }
+/**
+ * Safely set Sentry user. Silently fails on error.
+ */
 function safeSetUser(user) {
     try {
         const sdk = (0, sentry_runtime_1.getSentrySDK)();
         sdk?.setUser(user);
     }
     catch {
+        // Silently fail - analytics should never break SDK
     }
 }
+/**
+ * Build the SDK's internal Sentry sink — the bridge that forwards
+ * `Logger.log.*` output to the resolved Sentry SDK. Errors are captured as
+ * issues; warnings are recorded as breadcrumbs (see the severity policy on
+ * `SDKSentrySink`). The SDK reference is resolved lazily on each call so the
+ * sink tracks runtime swaps and stays correct under the test harness's mock.
+ *
+ * Every method is fully wrapped: a telemetry failure must never propagate back
+ * into the caller that was only trying to log.
+ */
 function createSentrySink() {
     return {
         captureException(error, context) {
@@ -64,9 +96,17 @@ function createSentrySink() {
                 if (!sdk)
                     return;
                 sdk.withScope((scope) => {
+                    // `beforeSend` drops any event not tagged as ours; the tag is global
+                    // already, but set it on the scope defensively in case a future
+                    // Sentry version starts withScope() from a clean slate.
                     scope.setTag('sdk', 'august-digital');
                     if (context) {
                         for (const [key, value] of Object.entries(context)) {
+                            // Promote the call-site label (e.g. 'getVault:loans') to a
+                            // scoped tag for grouping/filtering. Cardinality is bounded by
+                            // the number of Logger call sites (~150) and the tag is
+                            // event-scoped, not a global sticky tag — so it does not run
+                            // afoul of the bounded-tag rule in CLAUDE.md §8.4.
                             if (key === 'tag' && typeof value === 'string') {
                                 scope.setTag('sdk.origin', value);
                             }
@@ -80,6 +120,7 @@ function createSentrySink() {
                 });
             }
             catch {
+                // Telemetry must never break the SDK.
             }
         },
         addBreadcrumb(breadcrumb) {
@@ -87,13 +128,31 @@ function createSentrySink() {
                 (0, sentry_runtime_1.getSentrySDK)()?.addBreadcrumb(breadcrumb);
             }
             catch {
+                // Telemetry must never break the SDK.
             }
         },
     };
 }
+/**
+ * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
+ * only refresh user identity and the cached API-key hash.
+ *
+ * @param config - Analytics configuration. Pass `tracesSampleRate` to
+ *   override the Phase 1/2 default of `1.0`.
+ * @param environment - Current environment (DEV or PROD).
+ * @param walletAddress - Optional wallet address for user identification.
+ * @param apiKey - Optional API key (hashed for identification).
+ * @param appName - Optional app-name slug. Set as the global `app.name`
+ *   tag on every event; falls back to `'unverified:anonymous'` when
+ *   omitted.
+ */
 function initializeSentry(config, environment, walletAddress, apiKey, appName) {
+    // SDK construction runs this multiple times (base + adapter constructors).
+    // Short-circuit so the disable-reason logs only once per process.
     if (isInitialized) {
         if (isEnabled) {
+            // Refresh cached apiKey before updateUser — otherwise a second SDK
+            // instance built with a different key is attributed to the first hash.
             if (apiKey !== undefined && apiKey !== cachedApiKey) {
                 cachedApiKey = apiKey;
                 updateUser(walletAddress, environment);
@@ -105,6 +164,7 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         }
         return;
     }
+    // Constructor config wins outright — no env override can re-enable it.
     if (config.enabled === false) {
         isEnabled = false;
         isInitialized = true;
@@ -140,6 +200,8 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
     try {
         const sdk = (0, sentry_runtime_1.getSentrySDK)();
         if (!sdk) {
+            // Both @sentry/node and @sentry/browser failed to resolve. Surface this
+            // because the alternative is silent telemetry loss.
             logger_1.Logger.log.warn('analytics.init.sentry-unavailable', {
                 runtime: (0, sentry_runtime_1.getSentryRuntime)(),
                 hint: 'Confirm @sentry/browser (or @sentry/node) is installed and reachable.',
@@ -147,6 +209,8 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
             isEnabled = false;
             return;
         }
+        // Clamp to Sentry's accepted [0, 1] so a typo'd rate doesn't silently
+        // reject the init.
         const rawSampleRate = typeof config.tracesSampleRate === 'number' &&
             Number.isFinite(config.tracesSampleRate)
             ? config.tracesSampleRate
@@ -154,6 +218,7 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         const tracesSampleRate = Math.max(0, Math.min(1, rawSampleRate));
         sdk.init({
             dsn: constants_1.SENTRY_DSN,
+            // TODO(post-verified-partner): ramp default down to ~0.1.
             tracesSampleRate,
             enableTracing: true,
             environment: environment.toLowerCase(),
@@ -161,24 +226,36 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
             sendDefaultPii: true,
             integrations: [sdk.captureConsoleIntegration({ levels: ['error'] })],
             beforeSend(event) {
+                // Only send events tagged as SDK-related
                 if (event.tags?.sdk !== 'august-digital') {
                     return null;
                 }
                 return event;
             },
             beforeSendTransaction(transaction) {
+                // Always include transactions for performance tracking
                 return transaction;
             },
         });
+        // Set initial user identity
         updateUser(walletAddress, environment);
+        // Set global SDK tags
         safeSetTag('sdk', 'august-digital');
         safeSetTag('sdk.version', getSDKVersion());
         safeSetTag('sdk.runtime', (0, sentry_runtime_1.getSentryRuntime)());
+        // `app.name` is the dimension we filter on in Sentry to attribute
+        // events to a specific consuming application — see SDK quickstart docs.
         if (appName) {
             safeSetTag('app.name', appName);
         }
+        // `unverified:` prefix until the backend API-key → partner-id endpoint exists.
         safeSetTag('partner.id', appName ? `unverified:${appName}` : 'unverified:anonymous');
         safeSetTag('partner.tier', 'unverified');
+        // Bridge the SDK's structured logger into Sentry now that the SDK is live.
+        // Without this, Logger.log.error/warn are no-ops in production (no
+        // SDKLogger/structured logger is wired by default), so SDK-internal
+        // diagnostics never reach the dashboard. Errors → issues, warns →
+        // breadcrumbs.
         logger_1.Logger.setSentrySink(createSentrySink());
         isInitialized = true;
         logger_1.Logger.log.info('analytics.initialized', {
@@ -194,6 +271,13 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         isEnabled = false;
     }
 }
+/**
+ * Update the current user identity in Sentry.
+ * Called when wallet address changes.
+ *
+ * @param walletAddress - New wallet address (or undefined to clear)
+ * @param environment - Current environment
+ */
 function updateUser(walletAddress, environment = 'PROD') {
     if (!isEnabled)
         return;
@@ -202,10 +286,10 @@ function updateUser(walletAddress, environment = 'PROD') {
         const userId = (0, user_identity_1.getUserId)(currentIdentity);
         safeSetUser({
             id: userId,
-            username: userId,
+            username: userId, // Duplicate to username which is less likely to be filtered
             ip_address: '{{auto}}',
             data: {
-                userId,
+                userId, // Also store in data for redundancy
                 sessionId: currentIdentity.sessionId,
                 fingerprint: currentIdentity.fingerprint,
                 hasWallet: !!walletAddress,
@@ -216,8 +300,13 @@ function updateUser(walletAddress, environment = 'PROD') {
         });
     }
     catch {
+        // Silently fail
     }
 }
+/**
+ * Clear wallet from user identity.
+ * Called when user disconnects wallet.
+ */
 function clearUser() {
     if (!isEnabled)
         return;
@@ -240,16 +329,27 @@ function clearUser() {
         });
     }
     catch {
+        // Silently fail
     }
 }
+/**
+ * Check if analytics is enabled and initialized.
+ */
 function isAnalyticsEnabled() {
     return isEnabled && isInitialized;
 }
+/**
+ * Get the current Sentry instance for advanced usage.
+ * Returns null if analytics is disabled.
+ */
 function getSentry() {
     if (!isAnalyticsEnabled())
         return null;
     return (0, sentry_runtime_1.getSentrySDK)();
 }
+/**
+ * Reset analytics state (useful for testing).
+ */
 function resetAnalytics() {
     isInitialized = false;
     isEnabled = true;
@@ -258,6 +358,17 @@ function resetAnalytics() {
     logger_1.Logger.setSentrySink(null);
     (0, sentry_runtime_1.resetSentryRuntime)();
 }
+/**
+ * Capture an exception into Sentry with SDK-specific context. Use from
+ * top-level error handlers (CLI, middleware, unhandled rejections) to
+ * report failures that don't flow through the auto-instrumented method
+ * surface. No-ops when analytics is disabled.
+ *
+ * @param error - Thrown value. Non-Error values are wrapped.
+ * @param options - `surface` ('cli' | 'sdk' | 'react' | string), extra `tags`,
+ *   `extra` data, and a `flushTimeoutMs` to await before resolving (needed
+ *   in Node when the process is about to exit).
+ */
 async function captureSdkException(error, options) {
     if (!isAnalyticsEnabled())
         return;
@@ -266,6 +377,7 @@ async function captureSdkException(error, options) {
         if (!sdk)
             return;
         sdk.withScope((scope) => {
+            // Required so `beforeSend` doesn't drop the event.
             scope.setTag('sdk', 'august-digital');
             if (options?.surface) {
                 scope.setTag('sdk.surface', options.surface);
@@ -288,6 +400,7 @@ async function captureSdkException(error, options) {
         }
     }
     catch {
+        // Silently fail - analytics should never block error propagation
     }
 }
 //# sourceMappingURL=sentry.js.map

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

@@ -1,18 +1,45 @@
 import { IEnv } from '../../types';
+/**
+ * Configuration for SDK analytics/telemetry.
+ * Analytics are enabled by default (opt-out model).
+ */
 export interface IAnalyticsConfig {
+    /** Set to false to disable analytics. Default: true */
     enabled?: boolean;
+    /**
+     * Sentry trace sample rate. Defaults to `1.0` for the Phase 1/2 rollout;
+     * values outside `[0, 1]` are clamped.
+     */
     tracesSampleRate?: number;
 }
+/**
+ * User identity for analytics tracking.
+ * Multiple identifiers are used with priority: apiKeyHash > wallet > fingerprint > session
+ */
 export interface IUserIdentity {
+    /** SHA-256 hash prefix of API key (first 16 chars). Never stores raw key. */
     apiKeyHash?: string;
+    /** User's wallet address (lowercased) */
     walletAddress?: string;
+    /** Random UUID generated per SDK instance */
     sessionId: string;
+    /** Browser/environment fingerprint for cross-session tracking */
     fingerprint?: string;
+    /** Current environment */
     environment: IEnv;
+    /** Domain of the current environment */
     domain?: string;
 }
+/**
+ * Metrics for tracking SDK method calls.
+ */
 export interface IMethodCallMetrics {
     method: string;
+    /**
+     * Coarse-grained category from {@link METHOD_CATEGORIES} — e.g. `'read.vault'`,
+     * `'write.deposit'`. Used to roll calls up in the partner-usage dashboard
+     * without having to enumerate every method name.
+     */
     category?: string;
     chainId?: number;
     duration: number;

package/lib/core/analytics/user-identity.d.ts

@@ -1,7 +1,41 @@
 import { IEnv } from '../../types';
 import { IUserIdentity } from './types';
+/**
+ * Mask an API key, keeping only the last 5 characters visible.
+ * Example: "abcdefghij12345" -> "**********12345"
+ *
+ * @param apiKey - The raw API key to mask
+ * @returns Masked API key with last 5 characters visible
+ */
 export declare function hashApiKey(apiKey: string): string;
+/**
+ * Generate a session ID that persists for the SDK instance lifetime.
+ * Provides user continuity even when wallet is not connected.
+ *
+ * @returns UUID v4 session identifier
+ */
 export declare function getSessionId(): string;
+/**
+ * Generate a browser/environment fingerprint for cross-session tracking.
+ * Falls back gracefully in different environments.
+ *
+ * @returns Base64 encoded fingerprint string or undefined if unavailable
+ */
 export declare function generateFingerprint(): string | undefined;
+/**
+ * Create a composite user identity for analytics.
+ *
+ * @param apiKey - Optional API key (will be hashed, never stored raw)
+ * @param walletAddress - Optional wallet address
+ * @param environment - Current environment (DEV or PROD)
+ * @returns User identity object
+ */
 export declare function createUserIdentity(apiKey?: string, walletAddress?: string, environment?: IEnv): IUserIdentity;
+/**
+ * Generate a unique user ID for Sentry from identity components.
+ * Priority: apiKeyHash > wallet > fingerprint > session
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
 export declare function getUserId(identity: IUserIdentity): string;