@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/core/logger/index.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURATOR_ALERTS_DISABLE_ENV_VAR = exports.areCuratorAlertsEnabled = exports.configureCuratorAlerts = exports.Logger = exports.Slack = void 0;
+const sanitize_1 = require("../analytics/sanitize");
+let logger = null;
+let structuredLogger = null;
+let sentrySink = null;
+let isDev = false;
+function setLogger(customLogger) {
+    logger = customLogger;
+}
+/** Plug in an `ILogger`. Independent of `setLogger`; pass `null` to clear. */
+function setStructuredLogger(custom) {
+    structuredLogger = custom;
+}
+function getLogger() {
+    return logger;
+}
+function getStructuredLogger() {
+    return structuredLogger;
+}
+/**
+ * Wire (or clear, with `null`) the SDK's internal Sentry sink. Called by
+ * `initializeSentry` after a successful Sentry init, and reset by
+ * `resetAnalytics`. Not part of the integrator-facing API — applications wire
+ * their own logging through {@link setLogger} / {@link setStructuredLogger}.
+ *
+ * @internal
+ */
+function setSentrySink(sink) {
+    sentrySink = sink;
+}
+function setDevMode(devMode) {
+    isDev = devMode;
+}
+function isDevMode() {
+    return isDev;
+}
+/** Internal logger: DEV mode → console; production → SDKLogger. Sanitized either way. */
+const log = {
+    info: (tag, ...args) => {
+        const safeArgs = args.map((a) => (0, sanitize_1.sanitizeForLogging)(a));
+        if (isDev) {
+            console.log(`[${tag}]`, ...safeArgs);
+        }
+        structuredLogger?.info?.(tag, structuredContext(safeArgs));
+    },
+    warn: (tag, ...args) => {
+        const safeArgs = args.map((a) => (0, sanitize_1.sanitizeForLogging)(a));
+        if (isDev) {
+            console.warn(`[${tag}]`, ...safeArgs);
+        }
+        logger?.setTag('warning', tag);
+        structuredLogger?.warn?.(tag, structuredContext(safeArgs));
+        // Warnings ride along as breadcrumbs on the next captured event rather
+        // than becoming standalone issues — keeps Sentry volume bounded (see the
+        // severity policy on SDKSentrySink).
+        sentrySink?.addBreadcrumb({
+            category: 'sdk.logger',
+            level: 'warning',
+            message: tag,
+            data: structuredContext(safeArgs),
+        });
+    },
+    error: (tag, error, context) => {
+        const safeError = (0, sanitize_1.sanitizeError)(error);
+        const safeContext = context
+            ? (0, sanitize_1.sanitizeForLogging)(context)
+            : undefined;
+        if (isDev) {
+            console.error(`[${tag}]`, safeError);
+        }
+        logger?.captureException(safeError, { tag, ...safeContext });
+        structuredLogger?.error(tag, safeError, safeContext);
+        // The SDK's own bridge to Sentry: errors become issues. `safeError` /
+        // `safeContext` are already sanitized above, so the sink forwards as-is.
+        sentrySink?.captureException(safeError, { tag, ...safeContext });
+    },
+};
+/**
+ * Pino-friendly shape: if the first arg is a plain object, pass it through
+ * (with subsequent args as `extras`); otherwise wrap as `{ args }`.
+ */
+function structuredContext(args) {
+    if (args.length === 0)
+        return undefined;
+    const [first, ...rest] = args;
+    if (first &&
+        typeof first === 'object' &&
+        !Array.isArray(first) &&
+        !(first instanceof Error)) {
+        return rest.length === 0
+            ? first
+            : { ...first, extras: rest };
+    }
+    return { args };
+}
+const Logger = {
+    setLogger,
+    setStructuredLogger,
+    setSentrySink,
+    getLogger,
+    getStructuredLogger,
+    setDevMode,
+    isDevMode,
+    log,
+};
+exports.Logger = Logger;
+const slack = __importStar(require("./slack"));
+exports.Slack = slack;
+// Only the opt-out is public: code that drives the `Stellar` namespace directly
+// never constructs an `UpshiftSDK`, so `configureCuratorAlerts` is its sole way
+// to turn curator alerts off (and the only one that works in a browser, where
+// the env var is unreadable). The emitter itself stays deep-import only — a
+// partner has no reason to inject events into the relay.
+//
+// Safe to re-export from this barrel at all because `curator-alert` imports only
+// `types/`, `constants/` and leaf helpers under `core/analytics/` — never this
+// file — so there is no cycle back through the logger. `madge --circular` in CI
+// is the enforcement; this note is why it passes (CLAUDE.md §9).
+//
+// Both parameter types travel with the function: `ICuratorAlertsContext` is the
+// second argument's type, so without it a consumer cannot type a wrapper around
+// `configureCuratorAlerts` — and API Extractor flags it as a forgotten export
+// (CLAUDE.md §6).
+var curator_alert_1 = require("./curator-alert");
+Object.defineProperty(exports, "configureCuratorAlerts", { enumerable: true, get: function () { return curator_alert_1.configureCuratorAlerts; } });
+Object.defineProperty(exports, "areCuratorAlertsEnabled", { enumerable: true, get: function () { return curator_alert_1.areCuratorAlertsEnabled; } });
+Object.defineProperty(exports, "CURATOR_ALERTS_DISABLE_ENV_VAR", { enumerable: true, get: function () { return curator_alert_1.CURATOR_ALERTS_DISABLE_ENV_VAR; } });
+//# sourceMappingURL=index.js.map

package/lib/core/logger/slack.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Environment variable holding the Slack incoming-webhook to post SDK alerts
+ * to. Accepts either the full `https://hooks.slack.com/services/T…/B…/x…` URL
+ * or the bare `T…/B…/x…` path suffix.
+ */
+export declare const SLACK_WEBHOOK_ENV_VAR = "UPSHIFT_SDK_SLACK_WEBHOOK_URL";
+/**
+ * Resolve the Slack webhook to alert through.
+ *
+ * Why this replaced a hardcoded constant: a webhook path is a **bearer
+ * credential** — anyone holding it can post to the channel. The previous
+ * default embedded Upshift's own webhook as a string literal, which shipped in
+ * every published tarball and in the generated `.d.ts`, handing every consumer
+ * of the SDK write access to an internal Slack channel (CLAUDE.md §5: no
+ * secrets in client-reachable code). It also meant a consumer's alerts went to
+ * Upshift's channel rather than their own, with no way to redirect them.
+ *
+ * Resolution order:
+ *   1. `explicit` — passed by the caller, wins outright;
+ *   2. `UPSHIFT_SDK_SLACK_WEBHOOK_URL` in the environment;
+ *   3. none — alerting is disabled and the call becomes a no-op.
+ *
+ * Reading the env var per call (rather than once at module load) means a
+ * consumer configuring it after import still gets alerts, and a test can set
+ * and unset it without re-importing the module.
+ *
+ * @param explicit - Caller-supplied webhook, full URL or bare path suffix.
+ * @returns The bare `T…/B…/x…` path suffix, or `''` when unconfigured.
+ */
+export declare function resolveSlackWebhookUrl(explicit?: string): string;
+/**
+ * @deprecated Was a hardcoded webhook credential baked into the published
+ * bundle. It now resolves from {@link SLACK_WEBHOOK_ENV_VAR} and is `''` when
+ * unset. Call {@link resolveSlackWebhookUrl} instead — this export exists only
+ * so existing imports keep compiling, and is removed in the next major.
+ */
+export declare const DEFAULT_SLACK_WEBHOOK_URL = "";
+declare function error(options: {
+    title: string;
+    error: string;
+    poolAddress: string;
+    chainId: number;
+    slackWebookUrl: string;
+    address?: string;
+}): void;
+export declare const SLACK: {
+    error: typeof error;
+};
+export {};

package/lib/core/logger/slack.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLACK = exports.DEFAULT_SLACK_WEBHOOK_URL = exports.SLACK_WEBHOOK_ENV_VAR = void 0;
+exports.resolveSlackWebhookUrl = resolveSlackWebhookUrl;
+const core_1 = require("../helpers/core");
+const explorer_link_1 = require("../helpers/explorer-link");
+const sanitize_1 = require("../analytics/sanitize");
+const env_1 = require("../analytics/env");
+/**
+ * Environment variable holding the Slack incoming-webhook to post SDK alerts
+ * to. Accepts either the full `https://hooks.slack.com/services/T…/B…/x…` URL
+ * or the bare `T…/B…/x…` path suffix.
+ */
+exports.SLACK_WEBHOOK_ENV_VAR = 'UPSHIFT_SDK_SLACK_WEBHOOK_URL';
+/** `https://hooks.slack.com/services/` — stripped so both forms are accepted. */
+const SLACK_WEBHOOK_PREFIX = 'https://hooks.slack.com/services/';
+/**
+ * Resolve the Slack webhook to alert through.
+ *
+ * Why this replaced a hardcoded constant: a webhook path is a **bearer
+ * credential** — anyone holding it can post to the channel. The previous
+ * default embedded Upshift's own webhook as a string literal, which shipped in
+ * every published tarball and in the generated `.d.ts`, handing every consumer
+ * of the SDK write access to an internal Slack channel (CLAUDE.md §5: no
+ * secrets in client-reachable code). It also meant a consumer's alerts went to
+ * Upshift's channel rather than their own, with no way to redirect them.
+ *
+ * Resolution order:
+ *   1. `explicit` — passed by the caller, wins outright;
+ *   2. `UPSHIFT_SDK_SLACK_WEBHOOK_URL` in the environment;
+ *   3. none — alerting is disabled and the call becomes a no-op.
+ *
+ * Reading the env var per call (rather than once at module load) means a
+ * consumer configuring it after import still gets alerts, and a test can set
+ * and unset it without re-importing the module.
+ *
+ * @param explicit - Caller-supplied webhook, full URL or bare path suffix.
+ * @returns The bare `T…/B…/x…` path suffix, or `''` when unconfigured.
+ */
+function resolveSlackWebhookUrl(explicit) {
+    const raw = explicit?.trim() || (0, env_1.readEnv)(exports.SLACK_WEBHOOK_ENV_VAR)?.trim() || '';
+    return raw.startsWith(SLACK_WEBHOOK_PREFIX)
+        ? raw.slice(SLACK_WEBHOOK_PREFIX.length)
+        : raw;
+}
+/**
+ * @deprecated Was a hardcoded webhook credential baked into the published
+ * bundle. It now resolves from {@link SLACK_WEBHOOK_ENV_VAR} and is `''` when
+ * unset. Call {@link resolveSlackWebhookUrl} instead — this export exists only
+ * so existing imports keep compiling, and is removed in the next major.
+ */
+exports.DEFAULT_SLACK_WEBHOOK_URL = '';
+/** One-shot guard so an unconfigured webhook warns once, not per alert. */
+let warnedUnconfigured = false;
+function error(options) {
+    const { title, error, poolAddress, chainId, slackWebookUrl, address } = options;
+    // Falls back to the environment so a caller that passes nothing still
+    // alerts, provided the deployment configured a webhook of its own.
+    const webhookPath = resolveSlackWebhookUrl(slackWebookUrl);
+    if (!webhookPath) {
+        // Silence here used to be the hardcoded-default's job. Say it once, so a
+        // deployment that expected alerts learns they are off instead of watching
+        // an empty channel. Never log the webhook value itself.
+        if (!warnedUnconfigured) {
+            warnedUnconfigured = true;
+            console.warn(`#Slack.error: no webhook configured — set ${exports.SLACK_WEBHOOK_ENV_VAR} to enable Slack alerts. Alerts are disabled.`);
+        }
+        return;
+    }
+    if (!error) {
+        console.error('#Slack.error: error is undefined');
+        return;
+    }
+    if (!poolAddress) {
+        console.error('#Slack.error: poolAddress is undefined');
+        return;
+    }
+    if (!title) {
+        console.error('#Slack.error: type is undefined');
+        return;
+    }
+    if (!address) {
+        console.error('#Slack.error: address is undefined');
+        return;
+    }
+    if (!chainId) {
+        console.error('#Slack.error: chainId is undefined');
+        return;
+    }
+    (async () => {
+        const webhookUrl = `${SLACK_WEBHOOK_PREFIX}${webhookPath}`;
+        const safeError = (0, sanitize_1.sanitizeString)(String(error));
+        const safeTitle = (0, sanitize_1.sanitizeString)(String(title));
+        const data = {
+            text: `*Error: ${safeTitle}*\n${new Date().toUTCString()}\n\nPool: [${(0, core_1.truncate)(poolAddress)}](${(0, explorer_link_1.explorerLink)(poolAddress, chainId, 'address')})\n\n\nError: ${safeError}`,
+        };
+        const res = await fetch(webhookUrl, {
+            method: 'POST',
+            body: JSON.stringify(data),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (res?.status === 200)
+            console.log('#Slack.error: successfully sent');
+        else
+            console.error('#Slack.error:', res.status, res.statusText);
+    })().catch((e) => console.error('#Slack.error:', (0, sanitize_1.sanitizeString)(String(e?.message ?? e))));
+}
+exports.SLACK = {
+    error,
+};
+//# sourceMappingURL=slack.js.map

package/lib/core/vault-metadata.d.ts

@@ -0,0 +1,12 @@
+import type { IVaultMetadata } from '../types';
+/**
+ * Fetch vault metadata from the upshift API.
+ * Returns metadata including symbol, subgraph URL, and address for all vaults.
+ * @param options Request options including headers
+ * @returns Vault metadata object keyed by lowercase symbol
+ */
+export declare function fetchVaultMetadata(opts?: {
+    options?: {
+        headers?: Record<string, string>;
+    };
+}): Promise<IVaultMetadata>;

package/lib/core/vault-metadata.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchVaultMetadata = fetchVaultMetadata;
+const cache_1 = require("./cache");
+const core_1 = require("./constants/core");
+const logger_1 = require("./logger");
+/**
+ * Fetch vault metadata from the upshift API.
+ * Returns metadata including symbol, subgraph URL, and address for all vaults.
+ * @param options Request options including headers
+ * @returns Vault metadata object keyed by lowercase symbol
+ */
+async function fetchVaultMetadata(opts) {
+    const { options } = opts || {};
+    try {
+        const cacheKey = 'vaults_metadata';
+        if (cache_1.CACHE.has(cacheKey)) {
+            return cache_1.CACHE.get(cacheKey);
+        }
+        const response = await fetch(`${core_1.WEBSERVER_URL['upshift']}${core_1.WEBSERVER_ENDPOINTS.upshift.vaults.metadata}`, {
+            method: 'GET',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                'x-request-client': 'august-sdk',
+                ...options?.headers,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch vault metadata: ${response.statusText}`);
+        }
+        const metadata = await response.json();
+        cache_1.CACHE.set(cacheKey, metadata, { ttl: 10 * 60 * 1000 });
+        return metadata;
+    }
+    catch (e) {
+        logger_1.Logger.log.error('getVaultMetadata', e);
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        throw new Error(`#getVaultMetadata::${errorMessage}`);
+    }
+}
+//# sourceMappingURL=vault-metadata.js.map

package/lib/core/version-check.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Best-effort version check that nudges integrators when a newer
+ * `@upshiftfinance/sdk` is available on npm.
+ *
+ * Design constraints (all kept narrow on purpose):
+ *  - **No network call in production builds.** Most integrators ship the
+ *    SDK to end users in the browser; surprise registry pings on user page
+ *    loads are unacceptable. The check only fires when
+ *    `NODE_ENV !== 'production'` (i.e. local dev / CI environments).
+ *  - **Opt-out is supported in two places.** `UPSHIFT_SDK_DISABLE_VERSION_CHECK`
+ *    env var (set in CI to silence noise) or `versionCheck: { enabled: false }`
+ *    on the SDK constructor (programmatic opt-out, e.g. in your own libs
+ *    that wrap the SDK).
+ *  - **Fire-and-forget; never blocks construction.** The SDK constructor
+ *    must return synchronously. We schedule the check on the microtask
+ *    queue, abort after 5s, and swallow every error.
+ *  - **Once per session.** A module-level guard prevents repeated registry
+ *    hits when callers spin up multiple `UpshiftSDK` instances.
+ *  - **No new dependency.** Semver comparison is a tiny hand-rolled helper
+ *    rather than pulling in the `semver` package.
+ */
+/**
+ * Compare two numeric-dotted version strings. Returns:
+ *   - positive integer if `a > b`
+ *   - negative integer if `a < b`
+ *   - 0 if equal
+ *
+ * Pre-release suffixes (`-beta`, `-rc.1`) are stripped before comparison —
+ * we always treat any pre-release as equal to its base version. That keeps
+ * the comparison logic small and avoids false positives where an integrator
+ * on `4.27.4-beta.0` would otherwise be told to upgrade to the stable
+ * `4.27.3` they pre-released past.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Configuration knob exposed on `IUpshiftBase.versionCheck`. Defaulting to
+ * enabled keeps the nudge in front of integrators who haven't read the docs;
+ * setting `enabled: false` is the explicit opt-out for libraries that wrap
+ * the SDK and want their own update strategy.
+ */
+export interface IVersionCheckConfig {
+    /** Set to `false` to disable the registry check entirely. Default: `true`. */
+    enabled?: boolean;
+}
+/**
+ * Kick off a best-effort version check. Always returns synchronously.
+ *
+ * @param config - Optional config from `IUpshiftBase.versionCheck`
+ */
+export declare function runVersionCheck(config?: IVersionCheckConfig): void;
+/**
+ * Testing hook — resets the module-level guard so the check can run again
+ * in a fresh test case. Not part of the public API surface; kept here so
+ * unit tests don't have to monkey-patch internals.
+ *
+ * @internal
+ */
+export declare function _resetVersionCheckForTests(): void;

package/lib/core/version-check.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Best-effort version check that nudges integrators when a newer
+ * `@upshiftfinance/sdk` is available on npm.
+ *
+ * Design constraints (all kept narrow on purpose):
+ *  - **No network call in production builds.** Most integrators ship the
+ *    SDK to end users in the browser; surprise registry pings on user page
+ *    loads are unacceptable. The check only fires when
+ *    `NODE_ENV !== 'production'` (i.e. local dev / CI environments).
+ *  - **Opt-out is supported in two places.** `UPSHIFT_SDK_DISABLE_VERSION_CHECK`
+ *    env var (set in CI to silence noise) or `versionCheck: { enabled: false }`
+ *    on the SDK constructor (programmatic opt-out, e.g. in your own libs
+ *    that wrap the SDK).
+ *  - **Fire-and-forget; never blocks construction.** The SDK constructor
+ *    must return synchronously. We schedule the check on the microtask
+ *    queue, abort after 5s, and swallow every error.
+ *  - **Once per session.** A module-level guard prevents repeated registry
+ *    hits when callers spin up multiple `UpshiftSDK` instances.
+ *  - **No new dependency.** Semver comparison is a tiny hand-rolled helper
+ *    rather than pulling in the `semver` package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareSemver = compareSemver;
+exports.runVersionCheck = runVersionCheck;
+exports._resetVersionCheckForTests = _resetVersionCheckForTests;
+/** Module-level guard — flips to true after the first attempt. */
+let hasRunCheck = false;
+/** Public package name on npm — also the registry-API path component. */
+const NPM_PACKAGE = '@upshiftfinance/sdk';
+const REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE}/latest`;
+/** Timeout for the registry request. 5s is generous; faster failures stay silent. */
+const REQUEST_TIMEOUT_MS = 5_000;
+/**
+ * Read the current installed SDK version from the generated `version.ts`
+ * shim. Returns `null` when running from source (the file is gitignored and
+ * only emitted at publish time) — that's the signal to skip the check, since
+ * we have nothing meaningful to compare against.
+ */
+function getInstalledVersion() {
+    try {
+        // The require path is resolved relative to the compiled .js location,
+        // so it picks up `core/analytics/version.js` when it exists.
+        const mod = require('./analytics/version');
+        const v = mod.SDK_VERSION;
+        if (!v || v === 'development')
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read an environment variable in a way that's safe in both Node and the
+ * browser. `process` is typically undefined in browser bundles; even when
+ * it's stubbed by a bundler, `process.env` may be a frozen object that
+ * throws on missing-key access in some setups — try/catch covers that too.
+ */
+function readEnv(name) {
+    try {
+        if (typeof process !== 'undefined' && process.env) {
+            return process.env[name];
+        }
+    }
+    catch {
+        // Bundlers occasionally throw on `process.env` access. Treat as unset.
+    }
+    return undefined;
+}
+/**
+ * Compare two numeric-dotted version strings. Returns:
+ *   - positive integer if `a > b`
+ *   - negative integer if `a < b`
+ *   - 0 if equal
+ *
+ * Pre-release suffixes (`-beta`, `-rc.1`) are stripped before comparison —
+ * we always treat any pre-release as equal to its base version. That keeps
+ * the comparison logic small and avoids false positives where an integrator
+ * on `4.27.4-beta.0` would otherwise be told to upgrade to the stable
+ * `4.27.3` they pre-released past.
+ */
+function compareSemver(a, b) {
+    const stripPre = (v) => v.split('-')[0];
+    const parse = (v) => stripPre(v)
+        .split('.')
+        .map((part) => {
+        const n = Number.parseInt(part, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+    const aParts = parse(a);
+    const bParts = parse(b);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i++) {
+        const av = aParts[i] ?? 0;
+        const bv = bParts[i] ?? 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+/**
+ * Kick off a best-effort version check. Always returns synchronously.
+ *
+ * @param config - Optional config from `IUpshiftBase.versionCheck`
+ */
+function runVersionCheck(config) {
+    if (hasRunCheck)
+        return;
+    hasRunCheck = true;
+    if (config?.enabled === false)
+        return;
+    // Skip in production builds. We treat *anything* other than "production"
+    // as eligible (development, test, staging) — those are the envs where a
+    // console warning is helpful, not annoying.
+    if (readEnv('NODE_ENV') === 'production')
+        return;
+    // Explicit env opt-out (useful in CI where the console output is noise).
+    if (readEnv('UPSHIFT_SDK_DISABLE_VERSION_CHECK'))
+        return;
+    const installed = getInstalledVersion();
+    // No version file = local development from source. Nothing to compare.
+    if (!installed)
+        return;
+    // `fetch` is guaranteed in Node 18+ and all modern browsers, but the SDK
+    // supports older Node deployments via the React/Telegram bot integration.
+    // Gracefully no-op when missing.
+    if (typeof fetch !== 'function')
+        return;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const timeoutId = controller
+        ? setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+        : null;
+    // Run on the microtask queue so construction stays synchronous. The void
+    // expression discards the promise — we explicitly don't await it.
+    void (async () => {
+        try {
+            const res = await fetch(REGISTRY_URL, {
+                signal: controller?.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (!res.ok)
+                return;
+            const body = (await res.json());
+            const latest = typeof body.version === 'string' ? body.version : null;
+            if (!latest)
+                return;
+            if (compareSemver(latest, installed) > 0) {
+                // Use console.warn so the message is visible at the default log
+                // level in most setups, but distinguishable from real errors. This is
+                // an integrator-facing nudge — Logger.log.warn would make it a
+                // prod-silent breadcrumb, defeating the purpose.
+                // biome-ignore lint/suspicious/noConsole: integrator-facing version nudge must surface in every environment; Logger.log.warn would make it a prod-silent breadcrumb.
+                console.warn([
+                    `[${NPM_PACKAGE}] A newer version is available: ${installed} → ${latest}.`,
+                    `Run \`pnpm up ${NPM_PACKAGE}\` (or your package manager's equivalent) to update.`,
+                    `Silence this check with \`UPSHIFT_SDK_DISABLE_VERSION_CHECK=1\` or \`new UpshiftSDK({ versionCheck: { enabled: false }, ... })\`.`,
+                ].join('\n'));
+            }
+        }
+        catch {
+            // Network failure, aborted request, malformed JSON, frozen
+            // `console.warn`, etc. — every failure path stays silent. The check
+            // is purely an integrator-experience hint; it must never surface.
+        }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
+    })();
+}
+/**
+ * Testing hook — resets the module-level guard so the check can run again
+ * in a fresh test case. Not part of the public API surface; kept here so
+ * unit tests don't have to monkey-patch internals.
+ *
+ * @internal
+ */
+function _resetVersionCheckForTests() {
+    hasRunCheck = false;
+}
+//# sourceMappingURL=version-check.js.map

package/lib/evm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './methods';

package/lib/evm/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./methods"), exports);
+//# sourceMappingURL=index.js.map