upshift-finance 1.0.0

package/lib/core/index.d.ts

@@ -0,0 +1,23 @@
+export * from './fetcher';
+export * from './base.class';
+export * from './attribution';
+export * from './auth';
+export * from './logger';
+export * from './analytics';
+export * from './version-check';
+export * from './errors';
+export * from './constants/adapters';
+export * from './constants/core';
+export * from './constants/web3';
+export * from './constants/vaults';
+export * from './constants/swap-router';
+export * from './helpers/web3';
+export * from './helpers/multicall';
+export * from './helpers/vaults';
+export * from './helpers/chain-error';
+export * from './helpers/chain-support';
+export * from './helpers/core';
+export * from './helpers/adapters';
+export * from './helpers/signer';
+export * from './helpers/swap-router';
+export * from './helpers/revert-decode';

package/lib/core/index.js

@@ -0,0 +1,40 @@
+"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("./fetcher"), exports);
+__exportStar(require("./base.class"), exports);
+__exportStar(require("./attribution"), exports);
+__exportStar(require("./auth"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./analytics"), exports);
+__exportStar(require("./version-check"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./constants/adapters"), exports);
+__exportStar(require("./constants/core"), exports);
+__exportStar(require("./constants/web3"), exports);
+__exportStar(require("./constants/vaults"), exports);
+__exportStar(require("./constants/swap-router"), exports);
+__exportStar(require("./helpers/web3"), exports);
+__exportStar(require("./helpers/multicall"), exports);
+__exportStar(require("./helpers/vaults"), exports);
+__exportStar(require("./helpers/chain-error"), exports);
+__exportStar(require("./helpers/chain-support"), exports);
+__exportStar(require("./helpers/core"), exports);
+__exportStar(require("./helpers/adapters"), exports);
+__exportStar(require("./helpers/signer"), exports);
+__exportStar(require("./helpers/swap-router"), exports);
+__exportStar(require("./helpers/revert-decode"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,98 @@
+/**
+ * Sentry-compatible logger shape — `@sentry/browser` can be passed directly.
+ */
+export type SDKLogger = {
+    setTag: (key: string, value: string) => void;
+    captureException: (err: unknown, context?: Record<string, any>) => void;
+};
+/**
+ * Minimal breadcrumb shape forwarded to the internal Sentry sink. Mirrors the
+ * subset of Sentry's `Breadcrumb` the SDK populates, kept local so the logger
+ * stays decoupled from `@sentry/*` — and, more importantly, so it never has to
+ * import the analytics layer (which imports the logger, and would otherwise
+ * form a cycle; see CLAUDE.md §9).
+ *
+ * @internal
+ */
+export interface SDKBreadcrumb {
+    /** Breadcrumb grouping key. Always `'sdk.logger'` for logger-sourced crumbs. */
+    category: string;
+    /** Short, low-cardinality label — the call-site tag passed to `Logger.log.*`. */
+    message: string;
+    /** Severity. Logger warnings map to `'warning'`. */
+    level: 'info' | 'warning' | 'error';
+    /** Already-sanitized structured context. */
+    data?: Record<string, unknown>;
+}
+/**
+ * The SDK's own always-on Sentry sink, wired by `initializeSentry` when
+ * analytics is enabled and cleared by `resetAnalytics`. This is deliberately
+ * distinct from the integrator-pluggable {@link SDKLogger} / {@link ILogger}
+ * slots: those belong to the consuming application, this one is the SDK's
+ * internal bridge so its diagnostics reach the partner-usage dashboard without
+ * the integrator having to wire anything.
+ *
+ * Severity policy (implemented in `analytics/sentry.ts`): `error` is captured
+ * as a Sentry issue via `captureException`; `warn` becomes a breadcrumb that
+ * rides along with the next captured event. `info` is intentionally not
+ * forwarded — method-call breadcrumbs from `instrumentClass` already cover the
+ * happy path, and forwarding every info line would only add noise/cost.
+ *
+ * @internal
+ */
+export interface SDKSentrySink {
+    /** Forward a (pre-sanitized) error to Sentry as an issue. */
+    captureException: (error: unknown, context?: Record<string, unknown>) => void;
+    /** Forward a (pre-sanitized) breadcrumb to the active Sentry scope. */
+    addBreadcrumb: (breadcrumb: SDKBreadcrumb) => void;
+}
+/**
+ * Structured logger interface (debug/info/warn/error). Sanitization runs
+ * before any method here is invoked, so implementations needn't scrub secrets.
+ *
+ * ```ts
+ * Logger.setStructuredLogger({
+ *   info:  (tag, ctx) => pino.info({ tag, ...ctx }),
+ *   warn:  (tag, ctx) => pino.warn({ tag, ...ctx }),
+ *   error: (tag, err, ctx) => pino.error({ tag, err, ...ctx }),
+ * });
+ * ```
+ */
+export interface ILogger {
+    debug?: (tag: string, context?: Record<string, unknown>) => void;
+    info?: (tag: string, context?: Record<string, unknown>) => void;
+    warn?: (tag: string, context?: Record<string, unknown>) => void;
+    error: (tag: string, error: unknown, context?: Record<string, unknown>) => void;
+}
+declare function setLogger(customLogger: SDKLogger): void;
+/** Plug in an `ILogger`. Independent of `setLogger`; pass `null` to clear. */
+declare function setStructuredLogger(custom: ILogger | null): void;
+declare function getLogger(): SDKLogger | null;
+declare function getStructuredLogger(): ILogger | null;
+/**
+ * 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
+ */
+declare function setSentrySink(sink: SDKSentrySink | null): void;
+declare function setDevMode(devMode: boolean): void;
+declare function isDevMode(): boolean;
+declare const Logger: {
+    setLogger: typeof setLogger;
+    setStructuredLogger: typeof setStructuredLogger;
+    setSentrySink: typeof setSentrySink;
+    getLogger: typeof getLogger;
+    getStructuredLogger: typeof getStructuredLogger;
+    setDevMode: typeof setDevMode;
+    isDevMode: typeof isDevMode;
+    log: {
+        info: (tag: string, ...args: any[]) => void;
+        warn: (tag: string, ...args: any[]) => void;
+        error: (tag: string, error: unknown, context?: Record<string, any>) => void;
+    };
+};
+import * as slack from './slack';
+export { slack as Slack, Logger };

package/lib/core/logger/index.js

@@ -0,0 +1,144 @@
+"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.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;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * The default Slack webhook URL for logging errors.
+ */
+export declare const DEFAULT_SLACK_WEBHOOK_URL = "T04CM84GAV6/B0A2DS3ST8C/FLtOA3Jna3FN7UO4DoGxHfhG";
+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,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLACK = exports.DEFAULT_SLACK_WEBHOOK_URL = void 0;
+const core_1 = require("../helpers/core");
+const explorer_link_1 = require("../helpers/explorer-link");
+const sanitize_1 = require("../analytics/sanitize");
+/**
+ * The default Slack webhook URL for logging errors.
+ */
+exports.DEFAULT_SLACK_WEBHOOK_URL = 'T04CM84GAV6/B0A2DS3ST8C/FLtOA3Jna3FN7UO4DoGxHfhG';
+function error(options) {
+    const { title, error, poolAddress, chainId, slackWebookUrl, address } = options;
+    if (!slackWebookUrl) {
+        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 = `https://hooks.slack.com/services/${slackWebookUrl}`;
+        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
+ * `@augustdigital/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.** `AUGUST_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 `AugustSDK` 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 `IAugustBase.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 `IAugustBase.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
+ * `@augustdigital/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.** `AUGUST_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 `AugustSDK` 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 = '@augustdigital/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 `IAugustBase.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('AUGUST_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 \`AUGUST_SDK_DISABLE_VERSION_CHECK=1\` or \`new AugustSDK({ 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