@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,57 @@
+/**
+ * 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 UpshiftAuthError(code, message, opts)`) that would
+ * misalign if we naively passed the sanitized message as the first arg.
+ *
+ * Every write onto the clone goes through `Object.defineProperty` rather than
+ * assignment: the clone inherits `err`'s prototype, and some libraries make
+ * properties read-only there — `@solana/web3.js` defines `name` as non-writable
+ * on its error classes (`TransactionExpiredTimeoutError`, …). Assigning to an
+ * inherited non-writable property throws a `TypeError` in strict mode, which
+ * would escape from inside a caller's `catch` (e.g. `Logger.log.error`) and
+ * replace the error being reported. Defining an own property shadows the
+ * prototype's instead; each one is writable, configurable and enumerable,
+ * exactly as the plain assignment used to create it.
+ *
+ * @param err - Any caught value; non-`Error` values are returned unchanged.
+ * @returns A redacted clone for `Error` instances, otherwise `err` itself.
+ */
+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>;

package/lib/core/analytics/sanitize.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeString = sanitizeString;
+exports.sanitizeError = sanitizeError;
+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',
+    'apiKey',
+    'x-api-key',
+    'password',
+    'secret',
+    'token',
+    'bearer',
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'privatekey',
+    'private_key',
+    'privateKey',
+    'mnemonic',
+    'seed',
+    // RPC endpoints can carry the API key in the path (e.g. Alchemy `/v2/<key>`),
+    // so a `sorobanRpcUrl` / `rpcUrl` argument must never reach telemetry. Matched
+    // as a substring, so it also covers `sorobanRpcUrls` and snake_case variants.
+    'rpcurl',
+    'rpc_url',
+];
+/** 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]'],
+    [
+        /([?&](?:api[-_]?key|apikey|access[-_]?token|token|key|auth)=)[^&\s#]+/gi,
+        '$1[REDACTED]',
+    ],
+    [/(gateway\.thegraph\.com\/api\/)[A-Za-z0-9]{20,}(\/)/g, '$1[REDACTED]$2'],
+    // Provider path-embedded API keys (e.g. Alchemy `…/v2/<key>`, Infura `…/v3/<key>`):
+    // a 16+ char token right after a `/vN/` segment is a key, not a resource path.
+    [/(\/v\d+\/)[A-Za-z0-9_-]{16,}/g, '$1[REDACTED]'],
+    [/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;
+    let out = input;
+    for (const [pattern, replacement] of STRING_REDACTION_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    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 UpshiftAuthError(code, message, opts)`) that would
+ * misalign if we naively passed the sanitized message as the first arg.
+ *
+ * Every write onto the clone goes through `Object.defineProperty` rather than
+ * assignment: the clone inherits `err`'s prototype, and some libraries make
+ * properties read-only there — `@solana/web3.js` defines `name` as non-writable
+ * on its error classes (`TransactionExpiredTimeoutError`, …). Assigning to an
+ * inherited non-writable property throws a `TypeError` in strict mode, which
+ * would escape from inside a caller's `catch` (e.g. `Logger.log.error`) and
+ * replace the error being reported. Defining an own property shadows the
+ * prototype's instead; each one is writable, configurable and enumerable,
+ * exactly as the plain assignment used to create it.
+ *
+ * @param err - Any caught value; non-`Error` values are returned unchanged.
+ * @returns A redacted clone for `Error` instances, otherwise `err` itself.
+ */
+function sanitizeError(err) {
+    if (!(err instanceof Error))
+        return err;
+    const safe = Object.create(Object.getPrototypeOf(err));
+    const define = (key, value) => Object.defineProperty(safe, key, {
+        value,
+        writable: true,
+        configurable: true,
+        enumerable: true,
+    });
+    for (const key of Object.getOwnPropertyNames(err)) {
+        const value = err[key];
+        const redact = (key === 'message' || key === 'stack') && typeof value === 'string';
+        define(key, redact ? sanitizeString(value) : value);
+    }
+    if (!safe.message && typeof err.message === 'string') {
+        define('message', sanitizeString(err.message));
+    }
+    if (!safe.stack && typeof err.stack === 'string') {
+        define('stack', sanitizeString(err.stack));
+    }
+    define('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;
+    if (depth > 3)
+        return '[TRUNCATED]';
+    if (typeof input === 'string')
+        return sanitizeString(input);
+    if (typeof input === 'number' || typeof input === 'boolean')
+        return input;
+    if (input instanceof Error)
+        return sanitizeError(input);
+    if (Array.isArray(input)) {
+        return input.slice(0, 10).map((v) => sanitizeForLogging(v, depth + 1));
+    }
+    if (typeof input === 'object') {
+        return sanitizeObject(input, depth);
+    }
+    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));
+}
+function shapeOf(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    const t = typeof value;
+    if (t === 'boolean' || t === 'number' || t === 'bigint' || t === 'function') {
+        return t;
+    }
+    if (t === 'string') {
+        const s = value;
+        if (/^0x[a-fA-F0-9]{40}$/.test(s))
+            return 'address';
+        if (/^0x[a-fA-F0-9]{64}$/.test(s))
+            return 'tx-hash';
+        if (/^0x[a-fA-F0-9]{6,}$/.test(s))
+            return 'hex';
+        return 'string';
+    }
+    if (Array.isArray(value)) {
+        return `array(${value.length})`;
+    }
+    if (t === 'object') {
+        const keys = Object.keys(value).sort();
+        const capped = keys.slice(0, 12);
+        const more = keys.length > 12 ? `,+${keys.length - 12}` : '';
+        return `options{${capped.join(',')}${more}}`;
+    }
+    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) => {
+        const key = `arg${index}`;
+        if (arg === null || arg === undefined) {
+            sanitized[key] = arg;
+            return;
+        }
+        if (typeof arg === 'string') {
+            // Scrub embedded secrets, then truncate long strings.
+            const scrubbed = sanitizeString(arg);
+            sanitized[key] =
+                scrubbed.length > 100 ? `${scrubbed.substring(0, 100)}...` : scrubbed;
+            return;
+        }
+        if (typeof arg === 'number' || typeof arg === 'boolean') {
+            sanitized[key] = arg;
+            return;
+        }
+        if (typeof arg === 'object') {
+            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;
+        }
+        if (value === null || value === undefined) {
+            sanitized[key] = value;
+            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;
+            }
+            // Scrub embedded secrets (API keys in URL paths/queries, bearer tokens,
+            // JWTs, …) from free-form values before truncating — key-name matching
+            // alone misses a secret carried inside a value under a benign key.
+            const scrubbedValue = sanitizeString(value);
+            sanitized[key] =
+                scrubbedValue.length > 100
+                    ? `${scrubbedValue.substring(0, 100)}...`
+                    : scrubbedValue;
+            continue;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            sanitized[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            sanitized[key] =
+                value.length > 10
+                    ? { _type: 'array', length: value.length, _truncated: true }
+                    : value
+                        .slice(0, 10)
+                        .map((v) => typeof v === 'object' && v !== null
+                        ? sanitizeObject(v, depth + 1)
+                        : v);
+            continue;
+        }
+        if (typeof value === 'object') {
+            sanitized[key] = sanitizeObject(value, depth + 1);
+            continue;
+        }
+        sanitized[key] = `[${typeof value}]`;
+    }
+    return sanitized;
+}
+//# sourceMappingURL=sanitize.js.map

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

@@ -0,0 +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

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSentrySDK = getSentrySDK;
+exports.getSentryRuntime = getSentryRuntime;
+exports.resetSentryRuntime = resetSentryRuntime;
+const logger_1 = require("../logger");
+let cachedSdk = null;
+let detectedRuntime = 'unknown';
+function detectRuntime() {
+    try {
+        if (typeof window !== 'undefined' &&
+            typeof window.document !== 'undefined') {
+            return 'browser';
+        }
+        if (typeof process !== 'undefined' &&
+            process.versions?.node &&
+            typeof window === 'undefined') {
+            return 'node';
+        }
+    }
+    catch {
+        // Property access on locked-down globals can throw in some sandboxes.
+    }
+    return 'unknown';
+}
+/**
+ * Resolve a CommonJS `require` that can load `@sentry/node` at runtime without
+ * letting bundlers statically pull it into browser bundles.
+ *
+ * Why not `new Function('return require')`: the `Function` constructor
+ * evaluates in the *global* scope, and in a CommonJS module `require` is a
+ * module-wrapper parameter, not a global. That probe therefore returned
+ * `null` in every real Node process (only the REPL and `node -e` expose a
+ * global `require`), so the SDK silently fell back to `@sentry/browser` on
+ * Node and process-level exception capture never engaged.
+ *
+ * Resolution order:
+ * 1. The module-scoped `require` of this (CommonJS-compiled) file. In Node
+ *    and jest this is the real loader. Bundlers that target the browser
+ *    either leave `require` undefined (Vite/Rollup → `typeof` guard → null)
+ *    or substitute a stub that throws for unknown ids (webpack → caught by
+ *    the caller → falls through to `@sentry/browser`). The call site passes
+ *    the module id through a variable, so no bundler can statically resolve
+ *    `@sentry/node`.
+ * 2. `module.createRequire(__filename)` via `process.getBuiltinModule`
+ *    (Node ≥ 22.3) for hosts that rewrite `require` but keep `__filename`.
+ *
+ * @returns A `require`-compatible function, or `null` when none is reachable
+ *   (browser bundles, locked-down sandboxes).
+ */
+function getNodeRequire() {
+    try {
+        if (typeof require === 'function') {
+            return require;
+        }
+    }
+    catch {
+        // `require` can be a throwing getter under some sandboxes.
+    }
+    try {
+        const getBuiltin = process.getBuiltinModule;
+        if (typeof getBuiltin === 'function' && typeof __filename === 'string') {
+            const mod = getBuiltin('module');
+            if (typeof mod?.createRequire === 'function') {
+                return mod.createRequire(__filename);
+            }
+        }
+    }
+    catch {
+        // Not a Node runtime, or `module` is unavailable — fall through.
+    }
+    return null;
+}
+function loadSentrySDK() {
+    if (cachedSdk)
+        return cachedSdk;
+    detectedRuntime = detectRuntime();
+    if (detectedRuntime === 'node') {
+        const nodeRequire = getNodeRequire();
+        if (nodeRequire) {
+            try {
+                cachedSdk = nodeRequire('@sentry/node');
+                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.',
+                });
+            }
+        }
+    }
+    try {
+        cachedSdk = require('@sentry/browser');
+    }
+    catch (err) {
+        logger_1.Logger.log.warn('analytics.runtime.sentry-browser-missing', {
+            runtime: detectedRuntime,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        cachedSdk = null;
+    }
+    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';
+}
+//# sourceMappingURL=sentry-runtime.js.map

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>;