@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/analytics/sentry.js

@@ -0,0 +1,696 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSDKVersion = getSDKVersion;
+exports.resetErrorDedupe = resetErrorDedupe;
+exports.initializeSentry = initializeSentry;
+exports.updateUser = updateUser;
+exports.clearUser = clearUser;
+exports.isAnalyticsEnabled = isAnalyticsEnabled;
+exports.getSpanAttributes = getSpanAttributes;
+exports.getSentry = getSentry;
+exports.resetAnalytics = resetAnalytics;
+exports.captureSdkException = captureSdkException;
+const logger_1 = require("../logger");
+const app_name_1 = require("./app-name");
+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;
+/** Identity tags resolved at init, mirrored onto every `sdk.method` span. */
+let spanAttributes = {};
+/**
+ * The Upshift SDK build version, read from the generated `version.ts`.
+ * Falls back to `'development'` in an unbuilt checkout, where that file does
+ * not exist. Shared by the Sentry `release` tag and the
+ * `x-august-sdk-version` request header so the two can never disagree.
+ *
+ * @internal
+ */
+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';
+    }
+}
+/**
+ * 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
+    }
+}
+/**
+ * Chains whose errors are dropped before reaching Sentry.
+ *
+ * Mezo is muted by request: its public dRPC endpoint is unreliable enough that
+ * its failures dominated the error stream without ever describing an SDK
+ * defect. This is a deliberate blind spot — Mezo bugs (bad vault data, reverts,
+ * decode failures) are silenced along with the transport noise. Remove the
+ * entry to restore reporting; nothing else needs to change.
+ *
+ * Keyed by both the `chainIdToTagValue` slug and the numeric chain ID, because
+ * the two arrive on different events.
+ */
+const MUTED_CHAIN_SLUGS = new Set(['mezo']);
+/** Numeric chain IDs matching {@link MUTED_CHAIN_SLUGS}. */
+const MUTED_CHAIN_IDS = new Set(['31612']);
+/**
+ * Substrings that identify an event as Mezo-related regardless of tags.
+ *
+ * Tag-based matching alone is not enough: `sdk.chain` / `sdk.last_chainId`
+ * record the last *instrumented method's* chain, not the chain of the RPC that
+ * actually failed — the production Mezo batch-rejection events are tagged
+ * `sdk.chain: ethereum` while carrying `"requestUrl": "https://mezo.drpc.org"`
+ * in the message. Matching the message body catches those.
+ */
+const MUTED_CHAIN_MESSAGE_PATTERNS = [/mezo/i];
+/**
+ * Whether an event belongs to a muted chain and must not be sent.
+ *
+ * Checks, in order: the chain tags, then the event message and every exception
+ * value/type in the chain (an RPC failure's identifying detail often lives in a
+ * wrapped inner error rather than the top-level message).
+ *
+ * @param event - The Sentry event about to be sent.
+ * @returns `true` when the event should be dropped.
+ */
+function isMutedChainEvent(event) {
+    const chainTag = event.tags?.['sdk.chain'];
+    if (typeof chainTag === 'string' && MUTED_CHAIN_SLUGS.has(chainTag)) {
+        return true;
+    }
+    const chainIdTag = event.tags?.['sdk.last_chainId'];
+    if (typeof chainIdTag === 'string' && MUTED_CHAIN_IDS.has(chainIdTag)) {
+        return true;
+    }
+    const haystacks = [];
+    if (typeof event.message === 'string')
+        haystacks.push(event.message);
+    for (const exception of event.exception?.values ?? []) {
+        if (typeof exception.value === 'string')
+            haystacks.push(exception.value);
+        if (typeof exception.type === 'string')
+            haystacks.push(exception.type);
+    }
+    return haystacks.some((text) => MUTED_CHAIN_MESSAGE_PATTERNS.some((pattern) => pattern.test(text)));
+}
+/**
+ * Rolling window, in milliseconds, over which identical errors are counted.
+ */
+const ERROR_DEDUPE_WINDOW_MS = 60_000;
+/**
+ * Maximum captures of one error signature per {@link ERROR_DEDUPE_WINDOW_MS}.
+ * Chosen so a genuine, ongoing failure is still visible (and its rate
+ * observable via `sdk.suppressed_since_last`) while a hot loop hammering a
+ * broken RPC or a 404-per-borrower fan-out cannot bill thousands of identical
+ * events. Beyond this, further captures in the window are dropped.
+ */
+const ERROR_DEDUPE_MAX_PER_WINDOW = 3;
+/** Hard cap on tracked signatures, so the map cannot grow without bound. */
+const ERROR_DEDUPE_MAX_KEYS = 500;
+/**
+ * Per-signature capture bookkeeping for the dedupe window.
+ *
+ * Deliberately process-global, matching the Sentry client it feeds: the client
+ * is a singleton, so every `UpshiftSDK` instance in the process shares one
+ * event stream and one quota. The signature intentionally omits partner/app
+ * identity — a host serving several partners reports an identical upstream
+ * failure ≤{@link ERROR_DEDUPE_MAX_PER_WINDOW} times per window in aggregate,
+ * not per partner, because the failure is one event regardless of how many
+ * tenants observed it. Per-tenant attribution comes from the `partner.id` tag
+ * on the events that are sent, and `sdk.suppressed_since_last` preserves the
+ * true rate. `resetAnalytics()` clears this map for the whole process.
+ */
+const errorDedupeState = new Map();
+/**
+ * Strip the per-request variables out of an error message.
+ *
+ * Truncating at 120 characters is not enough on its own: the variable part is
+ * usually a vault or wallet address near the FRONT of the message
+ * (`Request timeout after 90s: /subaccount/0x3F13…/otc_positions`), so one
+ * failure mode still produced a distinct signature — and therefore its own
+ * private rate-limit allowance and its own Sentry issue — per address. That is
+ * how a single backend timeout became 5k events across a dozen issues in a day.
+ *
+ * Placeholders are kept structural (`/subaccount/<addr>/otc_positions`) so
+ * genuinely different endpoints and failure modes stay separate.
+ *
+ * @param message - The raw error message.
+ * @returns The message with addresses, numbers, and query strings masked.
+ */
+function normalizeErrorMessage(message) {
+    return message
+        .replace(/0x[0-9a-fA-F]{6,}/g, '<addr>')
+        .replace(/\?[^\s]*/g, '')
+        .replace(/\b\d{4,}\b/g, '<n>');
+}
+/**
+ * Build a low-cardinality signature for an error.
+ *
+ * The message is normalized (see {@link normalizeErrorMessage}) and then capped
+ * at 120 characters — enough to separate distinct failure modes without
+ * splitting one failure mode into thousands of unique keys.
+ *
+ * @param error - The normalized error being captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns A stable key identifying this class of failure.
+ */
+function errorSignature(error, origin) {
+    const tag = typeof origin === 'string' ? origin : '';
+    const message = normalizeErrorMessage(error.message || '').slice(0, 120);
+    return `${tag}|${error.name}|${message}`;
+}
+/**
+ * Decide whether an error should be sent to Sentry, applying a per-signature
+ * rolling rate limit.
+ *
+ * Why this exists: the SDK is called from server-rendered pages that fan out
+ * per vault and per borrower, so a single upstream condition (a 502 from the
+ * backend, an RPC rejecting a batch) reproduces on every iteration of every
+ * request. Those are the same event, and paying Sentry per copy buys no extra
+ * signal.
+ *
+ * Side effect: mutates {@link errorDedupeState}.
+ *
+ * @param error - The normalized error about to be captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns `send: false` to drop the event. When `send: true`, `suppressed` is
+ *   the number of copies dropped since the last event that was sent, and is
+ *   attached to the outgoing event so the true rate stays recoverable.
+ */
+function admitError(error, origin) {
+    const key = errorSignature(error, origin);
+    const now = Date.now();
+    const entry = errorDedupeState.get(key);
+    // Touch the key on every access so iteration order is true
+    // least-recently-used, not first-inserted: a Map's `set` on an existing key
+    // does NOT reorder it, so without the delete a signature that keeps
+    // recurring would hold its original position and be evicted ahead of a stale
+    // one-shot signature registered after it — silently handing the hot
+    // signature a fresh allowance every time it churned out of the map.
+    errorDedupeState.delete(key);
+    if (!entry || now - entry.windowStart >= ERROR_DEDUPE_WINDOW_MS) {
+        // Bound the map: drop the least-recently-used signature before inserting.
+        if (errorDedupeState.size >= ERROR_DEDUPE_MAX_KEYS) {
+            const oldest = errorDedupeState.keys().next();
+            if (!oldest.done)
+                errorDedupeState.delete(oldest.value);
+        }
+        const suppressed = entry?.suppressed ?? 0;
+        errorDedupeState.set(key, { windowStart: now, captured: 1, suppressed: 0 });
+        return { send: true, suppressed };
+    }
+    errorDedupeState.set(key, entry);
+    if (entry.captured < ERROR_DEDUPE_MAX_PER_WINDOW) {
+        // `suppressed` can only be non-zero once the allowance is exhausted, so
+        // inside the allowance there is never a carried count to report.
+        entry.captured += 1;
+        return { send: true, suppressed: 0 };
+    }
+    entry.suppressed += 1;
+    return { send: false, suppressed: entry.suppressed };
+}
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+function resetErrorDedupe() {
+    errorDedupeState.clear();
+}
+/**
+ * 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) {
+            try {
+                const sdk = (0, sentry_runtime_1.getSentrySDK)();
+                if (!sdk)
+                    return;
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                // Rate-limit identical failures before touching Sentry at all — the
+                // scope work and the event payload are both wasted if it is dropped.
+                const admission = admitError(normalized, context?.tag);
+                if (!admission.send)
+                    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);
+                            }
+                            else {
+                                scope.setExtra(key, value);
+                            }
+                        }
+                    }
+                    // Preserve the true failure rate even though copies were dropped.
+                    if (admission.suppressed > 0) {
+                        scope.setExtra('sdk.suppressed_since_last', admission.suppressed);
+                    }
+                    // Group by the same normalized signature the rate limiter uses.
+                    // Sentry's default grouping keys on the raw message, so one backend
+                    // timeout fans out into an issue per vault/wallet address — the
+                    // per-issue notification volume that flooded the on-call webhook.
+                    // Addresses stay recoverable from the event message and tags.
+                    scope.setFingerprint?.([
+                        'sdk',
+                        typeof context?.tag === 'string' ? context.tag : 'untagged',
+                        normalized.name,
+                        normalizeErrorMessage(normalized.message || '').slice(0, 120),
+                    ]);
+                    sdk.captureException(normalized);
+                });
+            }
+            catch {
+                // Telemetry must never break the SDK.
+            }
+        },
+        addBreadcrumb(breadcrumb) {
+            try {
+                (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.
+ *
+ * Breaking change in v9: `appName` moved from the optional fifth parameter
+ * to the required third parameter, so every telemetry stream carries an
+ * application identity (the `UpshiftSDK` constructor has required it since
+ * v5). Callers on the old positional order get a synchronous validation
+ * error rather than silently anonymous events.
+ *
+ * @param config - Analytics configuration. Pass `tracesSampleRate` to
+ *   override the default of `0.1`, and `surface` to label the emitting
+ *   surface (`sdk.surface` tag; defaults to `'sdk'`).
+ * @param environment - Current environment (DEV or PROD).
+ * @param appName - App-name slug, required. Set as the global `app.name`
+ *   tag on every event and used to derive `partner.id`. Identifier-shaped:
+ *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+ *   rules the `UpshiftSDK` constructor enforces.
+ * @param walletAddress - Optional wallet address for user identification.
+ * @param apiKey - Optional API key (hashed for identification).
+ * @throws UpshiftValidationError (code `INVALID_INPUT`) when `appName` is
+ *   missing, empty, mis-typed, out of the allowed length range, contains
+ *   disallowed characters, or is shaped like an EVM address. Thrown before
+ *   any analytics state mutates, even when analytics would be disabled by
+ *   config or environment gates.
+ */
+function initializeSentry(config, environment, appName, walletAddress, apiKey) {
+    // Enforce the identity contract before anything else — including the
+    // idempotency short-circuit and the disable gates — so a bad appName is
+    // equally loud on every call path and in every environment.
+    const validatedAppName = (0, app_name_1.validateAppName)(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);
+            }
+            else if (walletAddress !== currentIdentity?.walletAddress ||
+                environment !== currentIdentity?.environment) {
+                updateUser(walletAddress, environment);
+            }
+        }
+        return;
+    }
+    // Constructor config wins outright — no env override can re-enable it.
+    if (config.enabled === false) {
+        isEnabled = false;
+        isInitialized = true;
+        logger_1.Logger.log.info('analytics.disabled', { reason: 'config' });
+        return;
+    }
+    const forced = (0, env_1.isAnalyticsForcedOnViaEnv)();
+    if (!forced && (0, env_1.isAnalyticsDisabledViaEnv)()) {
+        isEnabled = false;
+        isInitialized = true;
+        logger_1.Logger.log.info('analytics.disabled', {
+            reason: 'UPSHIFT_SDK_DISABLE_ANALYTICS',
+        });
+        return;
+    }
+    if (!forced && (0, env_1.isNodeDevOrTestEnv)()) {
+        isEnabled = false;
+        isInitialized = true;
+        logger_1.Logger.log.info('analytics.disabled', {
+            reason: 'NODE_ENV',
+            nodeEnv: (0, env_1.readEnv)('NODE_ENV'),
+            hint: 'set UPSHIFT_SDK_FORCE_ANALYTICS=1 to override',
+        });
+        return;
+    }
+    if (!forced && (0, env_1.isLocalhost)()) {
+        isEnabled = false;
+        isInitialized = true;
+        logger_1.Logger.log.info('analytics.disabled', { reason: 'localhost' });
+        return;
+    }
+    cachedApiKey = apiKey;
+    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.',
+            });
+            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
+            : 0.1; // Phase 2 default — verified partners can opt into 1.0 explicitly
+        const tracesSampleRate = Math.max(0, Math.min(1, rawSampleRate));
+        // Hoisted so `release`, `august.sdk_version`, and the deprecated
+        // `sdk.version` are provably the same value rather than three separate
+        // reads of `./version`.
+        const sdkVersion = getSDKVersion();
+        sdk.init({
+            dsn: constants_1.SENTRY_DSN,
+            tracesSampleRate,
+            enableTracing: true,
+            environment: environment.toLowerCase(),
+            release: `august-sdk@${sdkVersion}`,
+            sendDefaultPii: true,
+            // SDK errors route through Logger.setSentrySink → captureException directly,
+            // so captureConsoleIntegration is redundant here. Omitting it also prevents
+            // consumer app console.error calls from being billed as SDK error events (the
+            // global sdk:'august-digital' tag would otherwise cause them to pass beforeSend).
+            integrations: [],
+            // Drop classes of event that are never SDK signal, as a backstop to the
+            // call-site demotions (see `logChainError` / `isUserRejectionError`).
+            // Scope is deliberately narrow: only categories that are noise in EVERY
+            // code path. Generic contract reverts (`CALL_EXCEPTION` / "missing revert
+            // data") are intentionally NOT listed — a reverted *write* tx is a real
+            // error we keep at `error` level, and only read-path reverts are demoted
+            // (surgically, at the call site).
+            ignoreErrors: [
+                // Wallet user-rejections are normal product behaviour, not an SDK fault.
+                /user rejected/i,
+                /user denied/i,
+                'ACTION_REJECTED',
+                // Local dev/test node leaking into a prod DSN: :8545 is the canonical
+                // Anvil/Hardhat port and is never a production RPC endpoint.
+                /ECONNREFUSED .*:8545/,
+                // UpshiftHistoryUnavailableError is a designed, documented outcome:
+                // the getter refuses to return a fabricated number when the indexer
+                // has no deposit/withdrawal history. It is thrown to the caller, who
+                // renders "temporarily unavailable" — the SDK is behaving correctly,
+                // so it is not an SDK issue. Indexer health is monitored separately.
+                /transaction history unavailable/i,
+            ],
+            beforeSend(event) {
+                // Only send events tagged as SDK-related
+                if (event.tags?.sdk !== 'august-digital') {
+                    return null;
+                }
+                // Muted chains (see MUTED_CHAIN_SLUGS) are dropped wholesale.
+                if (isMutedChainEvent(event)) {
+                    return null;
+                }
+                return event;
+            },
+        });
+        // Set initial user identity
+        updateUser(walletAddress, environment);
+        // Set global SDK tags
+        safeSetTag('sdk', 'august-digital');
+        // `august.sdk_version` is the queryable dimension for "which SDK build is
+        // this partner on" — the question that decides whether an error is a live
+        // defect or an already-shipped fix the consumer hasn't picked up.
+        //
+        // It exists because `sdk.version` (set below, kept for back-compat) is a
+        // RESERVED Sentry field: Sentry populates it with the version of its own
+        // client (`@sentry/core`). The custom tag is still stored, but a bare
+        // `sdk.version` in Discover resolves to Sentry's value, so the natural
+        // query silently answers the wrong question — uniform across every
+        // consumer, which makes it look like a working answer. Reaching the real
+        // value requires `tags[sdk.version]`, which nobody remembers to type.
+        //
+        // Both are low-cardinality version strings, so carrying the pair costs
+        // nothing against the tag budget (CLAUDE.md §8.4).
+        safeSetTag('august.sdk_version', sdkVersion);
+        /**
+         * @deprecated Shadowed by Sentry's reserved `sdk.version` field. Query
+         * `august.sdk_version` instead. Retained so existing saved queries,
+         * dashboards, and alert rules keep resolving; remove in the next major.
+         */
+        safeSetTag('sdk.version', sdkVersion);
+        const runtime = (0, sentry_runtime_1.getSentryRuntime)();
+        safeSetTag('sdk.runtime', runtime);
+        // `app.name` is the dimension we filter on in Sentry to attribute
+        // events to a specific consuming application — see SDK quickstart docs.
+        safeSetTag('app.name', validatedAppName);
+        // `unverified:` prefix until the backend API-key → partner-id endpoint exists.
+        const partnerId = `unverified:${validatedAppName}`;
+        safeSetTag('partner.id', partnerId);
+        // First-party apps are labelled so `partner.tier:unverified` already
+        // means "external integrator" before verification exists.
+        const partnerTier = constants_1.FIRST_PARTY_APP_NAMES.has(validatedAppName)
+            ? 'internal'
+            : 'unverified';
+        safeSetTag('partner.tier', partnerTier);
+        const surface = config.surface ?? 'sdk';
+        safeSetTag('sdk.surface', surface);
+        // Scope tags land only on the root span of a trace; child `sdk.method`
+        // spans get these copied on as attributes by `withMethodTracking`.
+        spanAttributes = {
+            'app.name': validatedAppName,
+            'partner.id': partnerId,
+            'partner.tier': partnerTier,
+            'sdk.runtime': runtime,
+            'sdk.surface': surface,
+            'august.sdk_version': sdkVersion,
+        };
+        // 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', {
+            runtime: (0, sentry_runtime_1.getSentryRuntime)(),
+            hint: 'Disable with { analytics: { enabled: false } } or UPSHIFT_SDK_DISABLE_ANALYTICS=1',
+        });
+    }
+    catch (err) {
+        logger_1.Logger.log.warn('analytics.init.failed', {
+            runtime: (0, sentry_runtime_1.getSentryRuntime)(),
+            error: err instanceof Error ? err.message : String(err),
+        });
+        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;
+    try {
+        currentIdentity = (0, user_identity_1.createUserIdentity)(cachedApiKey, walletAddress, environment);
+        const userId = (0, user_identity_1.getUserId)(currentIdentity);
+        safeSetUser({
+            id: userId,
+            username: userId, // Duplicate to username which is less likely to be filtered
+            ip_address: '{{auto}}',
+            data: {
+                userId, // Also store in data for redundancy
+                sessionId: currentIdentity.sessionId,
+                fingerprint: currentIdentity.fingerprint,
+                hasWallet: !!walletAddress,
+                hasApiKey: !!currentIdentity.apiKeyHash,
+                environment: currentIdentity.environment,
+                walletAddress: walletAddress || undefined,
+            },
+        });
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Clear wallet from user identity.
+ * Called when user disconnects wallet.
+ */
+function clearUser() {
+    if (!isEnabled)
+        return;
+    try {
+        const environment = currentIdentity?.environment || 'PROD';
+        currentIdentity = (0, user_identity_1.createUserIdentity)(cachedApiKey, undefined, environment);
+        const userId = (0, user_identity_1.getUserId)(currentIdentity);
+        safeSetUser({
+            id: userId,
+            username: userId,
+            ip_address: '{{auto}}',
+            data: {
+                userId,
+                sessionId: currentIdentity.sessionId,
+                fingerprint: currentIdentity.fingerprint,
+                hasWallet: false,
+                hasApiKey: !!currentIdentity.apiKeyHash,
+                environment: currentIdentity.environment,
+            },
+        });
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Check if analytics is enabled and initialized.
+ */
+function isAnalyticsEnabled() {
+    return isEnabled && isInitialized;
+}
+/**
+ * Identity tags resolved by `initializeSentry`, for `withMethodTracking` to
+ * copy onto each span as attributes. Sentry's span dataset carries scope tags
+ * on the root span only, so without this copy child `sdk.method` rows cannot
+ * be filtered by `app.name` or `partner.id`.
+ *
+ * @returns The tag snapshot, or `{}` until analytics has been enabled.
+ * @internal
+ */
+function getSpanAttributes() {
+    return spanAttributes;
+}
+/**
+ * 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;
+    currentIdentity = null;
+    cachedApiKey = undefined;
+    spanAttributes = {};
+    logger_1.Logger.setSentrySink(null);
+    (0, sentry_runtime_1.resetSentryRuntime)();
+    // The error rate limiter is process-lifetime state; a reset analytics layer
+    // must not inherit a half-full dedupe window from the previous one.
+    resetErrorDedupe();
+}
+/**
+ * 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' | 'mcp' | 'sdk' | 'react' | string)
+ *   overriding the init-time `sdk.surface` tag for this event, 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;
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        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);
+            }
+            if (options?.tags) {
+                for (const [k, v] of Object.entries(options.tags)) {
+                    scope.setTag(k, v);
+                }
+            }
+            if (options?.extra) {
+                for (const [k, v] of Object.entries(options.extra)) {
+                    scope.setExtra(k, v);
+                }
+            }
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            sdk.captureException(normalized);
+        });
+        if (options?.flushTimeoutMs && options.flushTimeoutMs > 0) {
+            await sdk.flush(options.flushTimeoutMs);
+        }
+    }
+    catch {
+        // Silently fail - analytics should never block error propagation
+    }
+}
+//# sourceMappingURL=sentry.js.map