@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,55 @@
+import type { 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 `0.1`; values outside `[0, 1]`
+     * are clamped.
+     */
+    tracesSampleRate?: number;
+    /**
+     * Which Upshift surface is emitting telemetry, recorded once at init as the
+     * sticky `sdk.surface` tag on every event and span. The CLI passes `'cli'`
+     * and the MCP server `'mcp'`; applications embedding the SDK directly can
+     * leave the default `'sdk'`.
+     */
+    surface?: 'sdk' | 'cli' | 'mcp' | 'react' | string;
+}
+/**
+ * User identity for analytics tracking.
+ * Multiple identifiers are used with priority: apiKeyHash \> wallet \> domain \> fingerprint \> session
+ */
+export interface IUserIdentity {
+    /** Hex-encoded SHA-256 hash of the API key. Never stores the 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;
+    success: boolean;
+    errorType?: string;
+}

package/lib/core/analytics/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,55 @@
+import type { IEnv } from '../../types';
+import type { IUserIdentity } from './types';
+/**
+ * Hash an API key with SHA-256 for use as a Sentry-safe identity token.
+ *
+ * Only the hash is ever returned. The most recently hashed key and its hash
+ * are cached in memory, so a repeat call skips the digest and a different key
+ * replaces the cache instead of returning the previous key's hash.
+ *
+ * When the runtime has no usable `crypto.createHash` (e.g. a browser bundle
+ * without a `crypto` shim) this returns `''` rather than throwing, so the
+ * Sentry identity falls back to the next identifier instead of being dropped.
+ *
+ * @param apiKey - The raw API key to hash
+ * @returns Hex-encoded SHA-256 hash of `apiKey`, or `''` for an empty input or
+ *   when hashing is unavailable
+ */
+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 \> domain \> fingerprint \> session
+ *
+ * An API key identifies the integrator and a wallet identifies the end user,
+ * so both outrank the hosting domain — otherwise every visitor of one web app
+ * collapses into a single Sentry user. `domain` still ranks above the
+ * fingerprint, which nearly every runtime produces, so hostname attribution
+ * is not lost.
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
+export declare function getUserId(identity: IUserIdentity): string;

package/lib/core/analytics/user-identity.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashApiKey = hashApiKey;
+exports.getSessionId = getSessionId;
+exports.generateFingerprint = generateFingerprint;
+exports.createUserIdentity = createUserIdentity;
+exports.getUserId = getUserId;
+const uuid_1 = require("uuid");
+/** Memoised result of {@link loadCreateHash}; `null` once resolution has failed. */
+let cachedCreateHash;
+/**
+ * Resolve Node's `crypto.createHash` without a static `import`.
+ *
+ * Why: this module is reachable from the browser bundle, and a top-level
+ * `import { createHash } from 'crypto'` either breaks the bundle (no Node
+ * built-in in the browser) or forces consumers to ship a polyfill. Instead
+ * the built-in is looked up at call time:
+ *
+ * 1. `process.getBuiltinModule('crypto')` (Node >= 22.3, the SDK's supported
+ *    floor is Node 22). A plain property access, so bundlers never see a
+ *    `crypto` import, and it works under both CJS and ESM loaders.
+ * 2. The `new Function('return require')` trick from
+ *    `core/analytics/sentry-runtime.ts`, for CJS hosts that expose a global
+ *    `require` (opaque to bundler static analysis).
+ *
+ * In a browser, or under a strict CSP that blocks `new Function`, both steps
+ * yield `null`: hashing is reported unavailable and callers fall back to the
+ * next identifier (wallet / domain / session) instead of throwing.
+ *
+ * Node output is byte-for-byte the same SHA-256 hex as the former static
+ * import produced — partner ids persisted in Sentry stay stable.
+ *
+ * @returns The `createHash` function, or `null` when it cannot be loaded.
+ */
+function loadCreateHash() {
+    if (cachedCreateHash !== undefined)
+        return cachedCreateHash;
+    cachedCreateHash = null;
+    try {
+        const getBuiltin = globalThis.process?.getBuiltinModule;
+        const mod = typeof getBuiltin === 'function'
+            ? getBuiltin('crypto')
+            : undefined;
+        if (typeof mod?.createHash === 'function') {
+            cachedCreateHash = mod.createHash;
+            return cachedCreateHash;
+        }
+    }
+    catch {
+        // fall through to the require-based lookup
+    }
+    try {
+        const req = new Function('return typeof require === "function" ? require : null')();
+        const mod = req ? req('crypto') : null;
+        if (typeof mod?.createHash === 'function') {
+            cachedCreateHash = mod.createHash;
+        }
+    }
+    catch {
+        // leave null: hashing unavailable in this runtime
+    }
+    return cachedCreateHash;
+}
+/**
+ * SHA-256 a string to lowercase hex, or `undefined` when no hash
+ * implementation is available in this runtime.
+ */
+function sha256Hex(value) {
+    const createHash = loadCreateHash();
+    if (!createHash)
+        return undefined;
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Session ID persists for SDK instance lifetime */
+let sessionId = null;
+/** Raw API key the cached hash below was computed from — lets a key change invalidate the cache. */
+let cachedApiKey = null;
+/** SHA-256 hash of {@link cachedApiKey}. */
+let cachedApiKeyHash = null;
+/**
+ * Hash an API key with SHA-256 for use as a Sentry-safe identity token.
+ *
+ * Only the hash is ever returned. The most recently hashed key and its hash
+ * are cached in memory, so a repeat call skips the digest and a different key
+ * replaces the cache instead of returning the previous key's hash.
+ *
+ * When the runtime has no usable `crypto.createHash` (e.g. a browser bundle
+ * without a `crypto` shim) this returns `''` rather than throwing, so the
+ * Sentry identity falls back to the next identifier instead of being dropped.
+ *
+ * @param apiKey - The raw API key to hash
+ * @returns Hex-encoded SHA-256 hash of `apiKey`, or `''` for an empty input or
+ *   when hashing is unavailable
+ */
+function hashApiKey(apiKey) {
+    if (!apiKey)
+        return '';
+    if (cachedApiKey === apiKey && cachedApiKeyHash) {
+        return cachedApiKeyHash;
+    }
+    try {
+        const hash = sha256Hex(apiKey);
+        if (!hash)
+            return '';
+        cachedApiKeyHash = hash;
+        cachedApiKey = apiKey;
+        return cachedApiKeyHash;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 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
+ */
+function getSessionId() {
+    if (!sessionId) {
+        sessionId = (0, uuid_1.v4)();
+    }
+    return sessionId;
+}
+/**
+ * Generate a browser/environment fingerprint for cross-session tracking.
+ * Falls back gracefully in different environments.
+ *
+ * @returns Base64 encoded fingerprint string or undefined if unavailable
+ */
+function generateFingerprint() {
+    try {
+        // Browser environment
+        if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
+            const components = [
+                navigator.userAgent,
+                navigator.language,
+                new Date().getTimezoneOffset().toString(),
+                typeof screen !== 'undefined' ? screen.width?.toString() : '',
+                typeof screen !== 'undefined' ? screen.height?.toString() : '',
+                typeof screen !== 'undefined' ? screen.colorDepth?.toString() : '',
+            ].filter(Boolean);
+            // Create a simple hash from components
+            const hash = sha256Hex(components.join('|'));
+            return hash?.substring(0, 32);
+        }
+        // Node.js environment
+        if (typeof process !== 'undefined' && process.platform) {
+            const components = [process.platform, process.arch, process.version];
+            const hash = sha256Hex(components.join('|'));
+            return hash?.substring(0, 32);
+        }
+    }
+    catch {
+        // Silently fail if fingerprinting is not possible
+        return undefined;
+    }
+    return 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
+ */
+function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
+    let domain;
+    try {
+        if (typeof window !== 'undefined' && window.location) {
+            domain = window.location.hostname;
+        }
+        else if (typeof process !== 'undefined' && process.env) {
+            domain = process.env.VERCEL_PROJECT_PRODUCTION_URL || undefined;
+        }
+    }
+    catch {
+        // Silently fail - domain is optional
+    }
+    return {
+        apiKeyHash: apiKey ? hashApiKey(apiKey) : undefined,
+        walletAddress: walletAddress?.toLowerCase(),
+        sessionId: getSessionId(),
+        fingerprint: generateFingerprint(),
+        environment,
+        domain,
+    };
+}
+/**
+ * Generate a unique user ID for Sentry from identity components.
+ * Priority: apiKeyHash \> wallet \> domain \> fingerprint \> session
+ *
+ * An API key identifies the integrator and a wallet identifies the end user,
+ * so both outrank the hosting domain — otherwise every visitor of one web app
+ * collapses into a single Sentry user. `domain` still ranks above the
+ * fingerprint, which nearly every runtime produces, so hostname attribution
+ * is not lost.
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
+function getUserId(identity) {
+    if (identity.apiKeyHash) {
+        return `apikey:${identity.apiKeyHash}`;
+    }
+    if (identity.walletAddress) {
+        return `wallet:${identity.walletAddress}`;
+    }
+    if (identity.domain) {
+        return `domain:${identity.domain}`;
+    }
+    if (identity.fingerprint) {
+        return `fp:${identity.fingerprint}`;
+    }
+    return `session:${identity.sessionId}`;
+}
+//# sourceMappingURL=user-identity.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated at build time from package.json version
+ * This file is gitignored and regenerated by every build
+ */
+export declare const SDK_VERSION = "0.2.0";

package/lib/core/analytics/version.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated at build time from package.json version
+ * This file is gitignored and regenerated by every build
+ */
+exports.SDK_VERSION = '0.2.0';
+//# sourceMappingURL=version.js.map

package/lib/core/attribution.d.ts

@@ -0,0 +1,159 @@
+/**
+ * ERC-8021 transaction attribution (Base Builder Codes).
+ *
+ * ERC-8021 appends an attribution suffix to transaction calldata. Contracts
+ * decode their ABI-encoded arguments normally and ignore the trailing bytes,
+ * while offchain indexers (e.g. base.dev analytics for Base Builder Codes)
+ * read the suffix to attribute the transaction to the originating app.
+ *
+ * This is a leaf module: process-global state configured once via
+ * {@link IUpshiftBase.attribution} in the SDK constructor and read by the
+ * EVM write paths (the normalized-signer wrap in the EVM adapter and the
+ * cross-chain vault `writeContract` calls).
+ *
+ * @module attribution
+ */
+/**
+ * The 16-byte ERC-8021 suffix terminator. The last 16 bytes of an attributed
+ * transaction's calldata are always this marker; parsers read backwards from
+ * it to recover the schema ID and builder codes.
+ */
+export declare const ERC8021_MARKER = "80218021802180218021802180218021";
+/**
+ * ERC-8021 builder-code attribution and the SwapRouter origin code — independent; set either or both.
+ *
+ * @example
+ * ```typescript
+ * const sdk = new UpshiftSDK({
+ *   appName: 'my-app',
+ *   providers: { 8453: 'https://...' },
+ *   keys: { upshift: '...' },
+ *   attribution: { builderCodes: ['bc_abc123'] },
+ * });
+ * ```
+ */
+export interface IAttributionConfig {
+    /**
+     * Builder codes to embed in the suffix, e.g. from base.dev registration
+     * (`bc_…`). ASCII strings of 1–64 characters each; the comma-joined list
+     * must fit in 255 bytes (schema 0 length prefix is a single byte). Omit to
+     * send no ERC-8021 suffix.
+     */
+    builderCodes?: string[];
+    /**
+     * EVM chain IDs to attribute. Omit to attribute writes on every EVM chain
+     * (the suffix is inert on chains without an ERC-8021 indexer and costs
+     * ~16 gas per non-zero byte). When set, gating is fail-closed: writes on
+     * other chains — and writes whose chain ID cannot be determined — are sent
+     * without the suffix.
+     *
+     * Over-attribution is not harmless. The suffix makes calldata longer than
+     * the ABI encoding of the call, which breaks clear-signing on hardware
+     * wallets: a Ledger rejects an over-long ERC-20 `approve` with
+     * `EthAppCommandError: Invalid data 6a80`, so an unattributed chain that
+     * receives the suffix anyway cannot be transacted on from a Ledger at all.
+     */
+    chains?: number[];
+    /**
+     * SwapRouter origin (referral / fee-sharing) code: the `bytes32` registered
+     * via the router's `addOrigin`, as `0x` + 64 hex chars. Every Ethereum
+     * mainnet SwapRouter deposit carries it unless the call passes its own
+     * `originCode`; it is never sent on another chain. Omit to send the
+     * all-zero sentinel (no origin fee). Unaffected by `chains`. An
+     * unregistered code reverts with `InvalidOrigin` — check it with
+     * `getOriginInfo` first.
+     */
+    originCode?: `0x${string}`;
+    /**
+     * When `true`, a deposit route that would use the SwapRouter with an
+     * `originCode` not registered there throws `UpshiftValidationError` before
+     * any transaction, instead of falling back to the vault's native path.
+     */
+    strictOrigin?: boolean;
+}
+/**
+ * Build an ERC-8021 schema-0 attribution suffix from builder codes.
+ *
+ * Layout (appended to calldata, read back-to-front by parsers):
+ * `ascii(codes.join(','))` ∥ codesLength (1 byte) ∥ schemaId `0x00` ∥
+ * 16-byte marker `0x80218021802180218021802180218021`.
+ *
+ * @param codes Builder codes as printable-ASCII strings (e.g. `bc_abc123`),
+ *   each 1–64 chars, no commas; the comma-joined list must be ≤ 255 bytes.
+ * @returns `0x`-prefixed hex suffix ready to concatenate onto calldata.
+ * @throws Error when `codes` is empty, a code contains a comma or
+ *   non-printable/non-ASCII characters, or the joined list exceeds 255 bytes.
+ * @example
+ * ```typescript
+ * buildAttributionSuffix(['baseapp', 'morpho']);
+ * // '0x626173656170702c6d6f7270686f0e0080218021802180218021802180218021'
+ * ```
+ */
+export declare function buildAttributionSuffix(codes: string[]): string;
+/**
+ * Set (or clear) the process-global attribution config.
+ *
+ * Called unconditionally on every `UpshiftSDK` construction — an instance
+ * that omits `attribution` passes `null` and RESETS the state, so a prior
+ * instance's builder codes or origin code never leak into a later instance
+ * in the same process (same semantics as `setPublicApiBaseUrl`).
+ *
+ * @param config Attribution config from the SDK constructor, or `null` to
+ *   disable attribution.
+ * @throws Error when the config's builder codes fail validation — thrown
+ *   synchronously from the constructor so misconfiguration is caught at
+ *   init, not on the first write.
+ * @throws {@link UpshiftValidationError} when `originCode` is not a 32-byte
+ *   hex string.
+ */
+export declare function setAttribution(config: IAttributionConfig | null): void;
+/**
+ * Whether {@link IAttributionConfig.strictOrigin} is set on the SDK instance.
+ *
+ * @returns `true` when an unregistered origin code must fail a deposit.
+ */
+export declare function isStrictOrigin(): boolean;
+/**
+ * The SwapRouter origin code configured on the SDK instance via
+ * {@link IAttributionConfig.originCode}.
+ *
+ * @returns The `bytes32` code, or `null` when none is configured.
+ */
+export declare function getOriginCode(): `0x${string}` | null;
+/**
+ * Whether attribution is configured at all, independent of any chain gate.
+ *
+ * Call sites that need to know whether to resolve a chain ID before asking
+ * for the suffix use this; {@link getAttributionSuffix} applies the gate.
+ *
+ * @returns `true` when builder codes are configured.
+ */
+export declare function isAttributionEnabled(): boolean;
+/**
+ * Return the active ERC-8021 suffix for a write on the given chain, or
+ * `undefined` when attribution is off or the chain is not attributed.
+ *
+ * @param chainId EVM chain ID of the transaction, when the call site knows
+ *   it. When a `chains` restriction is configured, gating is fail-closed: an
+ *   omitted chain ID yields no suffix, since a suffix on an unattributed
+ *   chain buys nothing and breaks hardware-wallet clear-signing (see
+ *   {@link IAttributionConfig.chains}).
+ * @returns `0x`-prefixed hex suffix, or `undefined` when nothing should be
+ *   appended.
+ */
+export declare function getAttributionSuffix(chainId?: number): string | undefined;
+/**
+ * Append the active attribution suffix to calldata.
+ *
+ * No-ops (returns `data` unchanged) when attribution is off, the chain is
+ * not attributed (including an unknown chain under a `chains` restriction),
+ * `data` is empty/absent (plain value transfers are never
+ * attributed), or `data` already ends with the ERC-8021 marker (guards
+ * against double-appending when an upstream layer — e.g. a wagmi config
+ * `dataSuffix` — already attributed the transaction).
+ *
+ * @param data `0x`-prefixed calldata of the outgoing transaction.
+ * @param chainId EVM chain ID of the transaction, when known.
+ * @returns Calldata with the suffix appended, or the input unchanged.
+ */
+export declare function appendAttributionSuffix(data: string | undefined | null, chainId?: number): string | undefined | null;