@upshiftfinance/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,100 @@
+import type * as Sentry from '@sentry/browser';
+import type { IEnv } from '../../types';
+import type { IAnalyticsConfig } from './types';
+/**
+ * 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
+ */
+export declare function getSDKVersion(): string;
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+export declare function resetErrorDedupe(): void;
+/**
+ * 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.
+ */
+export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, appName: string, walletAddress?: string, apiKey?: 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;
+/**
+ * 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
+ */
+export declare function getSpanAttributes(): Readonly<Record<string, string>>;
+/**
+ * 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' | '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).
+ */
+export declare function captureSdkException(error: unknown, options?: {
+    surface?: 'cli' | 'mcp' | 'sdk' | 'react' | string;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    flushTimeoutMs?: number;
+}): Promise<void>;