@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/sui/transformer.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformEmberVaultToIVault = transformEmberVaultToIVault;
+exports.transformEmberVaultsToIVaults = transformEmberVaultsToIVaults;
+const core_1 = require("../../core");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+/**
+ * Transform Ember vault to IVault format
+ */
+function transformEmberVaultToIVault(emberVault) {
+    const depositTokenDecimals = emberVault.depositCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
+    const receiptTokenDecimals = emberVault.receiptCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
+    const returnObj = {
+        chainId: constants_1.SUI_CHAIN_ID,
+        maxDailyDrawdown: 0,
+        risk: 'medium',
+        lagDuration: 0,
+        address: emberVault.address,
+        name: emberVault.name,
+        logoUrl: emberVault.logoUrl || '',
+        apy: {
+            apy: (0, utils_1.convertFromE9)(emberVault.reportedApy?.reportedApyE9 || 0) * 100,
+            pointsApy: null,
+            campaignApy: null,
+            explainer: '',
+            liquidApy: 0,
+            rewardsClaimable: 0,
+            rewardsCompounded: 0,
+            underlyingApy: (0, utils_1.convertFromE9)(emberVault.reportedApy?.reportedApyE9 || 0) * 100,
+        },
+        historical_apy: {
+            7: (0, utils_1.convertFromE9)(emberVault.reportedApy?.reportedApyE9 || 0),
+        },
+        strategists: (emberVault.managers ||
+            emberVault.subAccounts?.map((s) => s.manager) ||
+            []).map((manager) => ({
+            address: manager?.id || '',
+            logo: manager?.logoUrl || '',
+            name: manager?.name?.toLowerCase() === 'gamma'
+                ? 'Gamma Research'
+                : manager?.name || 'Unknown',
+            type: 'subaccount',
+            website_url: null,
+        })),
+        fees: {
+            performance: (0, utils_1.convertFromE9)(emberVault.weeklyPerformanceFeeBpsE9 || 0) /
+                constants_1.EMBER_DEFAULTS.BPS_TO_PERCENT,
+            management: (0, utils_1.convertFromE9)(emberVault.managementFeePercentE9 || 0) * 100,
+            isManagementWaived: false,
+            managementFeeWaivedUntilDate: null,
+            managementFeeWaivedUntilTvl: null,
+            isPerformanceWaived: false,
+            performanceFeeWaivedUntilDate: null,
+            performanceFeeWaivedUntilTvl: null,
+        },
+        rewards: {
+            points: '0',
+            multiplier: 0,
+            multipliers: [],
+            additionalPoints: [],
+            additionalPointsDetailed: [],
+        },
+        version: constants_1.EMBER_DEFAULTS.VERSION,
+        description: emberVault.description || '',
+        startDatetime: new Date(emberVault.createdAt || Date.now()).toISOString(),
+        status: emberVault.status === 'deprecated' ? 'closed' : 'active',
+        tags: ['Sui DeFi', emberVault.publicType].filter(Boolean),
+        isFeatured: false,
+        isSpotlighted: false,
+        withdrawalOnly: undefined,
+        isVisible: emberVault.status === 'active' || emberVault.status === 'beta',
+        reserveTarget: 0,
+        reserveTolerance: 0,
+        isDepositPaused: emberVault.status === 'deprecated',
+        decimals: receiptTokenDecimals,
+        isWithdrawalPaused: emberVault.status === 'deprecated',
+        operator: '',
+        idleAssets: (0, core_1.toNormalizedBn)(0, receiptTokenDecimals),
+        depositAssets: [
+            {
+                address: emberVault.depositCoin?.address,
+                symbol: emberVault.depositCoin?.symbol || '',
+                decimals: depositTokenDecimals,
+            },
+        ],
+        totalAssets: (0, core_1.toNormalizedBn)(BigInt(emberVault.totalDeposits || '0'), depositTokenDecimals),
+        /**
+         * PLACEHOLDER: `totalSupply` mirrors `totalDeposits`, so any share price
+         * derived as totalAssets / totalSupply is always 1.0 for Ember vaults and
+         * is NOT the real receipt-token price. Ember's `rateE9` is not read: its
+         * exact semantics (and whether `totalDeposits` is current TVL or a
+         * cumulative figure) are not documented by the Ember API, so it is not
+         * used to derive supply until that is confirmed.
+         */
+        totalSupply: (0, core_1.toNormalizedBn)(BigInt(emberVault.totalDeposits || '0'), receiptTokenDecimals),
+        maxSupply: (0, core_1.toNormalizedBn)(BigInt(emberVault.maxDepositsAllowed || '0'), depositTokenDecimals),
+        receipt: {
+            symbol: emberVault.receiptCoin?.symbol || '',
+            address: emberVault.receiptCoin?.address,
+            decimals: receiptTokenDecimals,
+        },
+        composabilityIntegrations: [],
+        eoa_operators: [],
+        operators: [],
+    };
+    return returnObj;
+}
+/**
+ * Transform multiple Ember vaults
+ */
+function transformEmberVaultsToIVaults(emberVaults) {
+    return emberVaults.map(transformEmberVaultToIVault);
+}
+//# sourceMappingURL=transformer.js.map

package/lib/adapters/sui/types.d.ts

@@ -0,0 +1,70 @@
+import type { IHIstoricalSnapshot } from '../../types';
+export interface IEmberVault {
+    address: string;
+    id: string;
+    name: string;
+    description: string;
+    logoUrl: string;
+    status: 'active' | 'beta' | 'deprecated';
+    publicType: string;
+    strategy: string;
+    createdAt: number;
+    totalDeposits: string;
+    totalDepositsInUsdE9: string;
+    maxDepositsAllowed: string;
+    rateE9: string;
+    managementFeePercentE9: string;
+    weeklyPerformanceFeeBpsE9: string;
+    withdrawalPeriodDays: number;
+    minWithdrawalSharesE9: string;
+    historicalSnapshots?: IHIstoricalSnapshot[];
+    max_drawdown?: number | null;
+    depositCoin: {
+        address: string;
+        symbol: string;
+        name: string;
+        decimals: number;
+        logoUrl: string;
+        priceE9: string;
+        type: string;
+    };
+    receiptCoin: {
+        address: string;
+        symbol: string;
+        name: string;
+        decimals: number;
+        logoUrl: string;
+        priceE9: string;
+        type: string;
+    };
+    reportedApy: {
+        apyE9: string;
+        reportedApyE9: string;
+        updatedAt: string;
+    };
+    managers: Array<{
+        id: string;
+        name: string;
+        logoUrl: string;
+        websiteUrl: string;
+    }>;
+    subAccounts: Array<{
+        address: string;
+        manager: {
+            id: string;
+            name: string;
+            logoUrl: string;
+            websiteUrl: string;
+        };
+    }>;
+    /**
+     * Ember reward entries. Their shape is not documented by the Ember API and
+     * the SDK does not read them, so they are typed `unknown` — narrow before use.
+     */
+    rewards: unknown[];
+}
+export interface IFetchEmberVaultsOptions {
+    limit?: number;
+    offset?: number;
+    status?: string;
+}

package/lib/adapters/sui/types.js

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

package/lib/adapters/sui/utils.d.ts

@@ -0,0 +1,8 @@
+export { isSuiAddress } from '../../core/helpers/chain-address';
+/**
+ * Whether `chainId` is the SDK's Sui chain ID ({@link SUI_CHAIN_ID}, `-2`).
+ *
+ * @param chainId - Numeric chain ID, e.g. a backend vault row's `chain`.
+ * @returns `true` only for `-2`.
+ */
+export declare function isSuiVault(chainId: number): boolean;

package/lib/adapters/sui/utils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSuiAddress = void 0;
+exports.isSuiVault = isSuiVault;
+const constants_1 = require("./constants");
+var chain_address_1 = require("../../core/helpers/chain-address");
+Object.defineProperty(exports, "isSuiAddress", { enumerable: true, get: function () { return chain_address_1.isSuiAddress; } });
+/**
+ * Whether `chainId` is the SDK's Sui chain ID ({@link SUI_CHAIN_ID}, `-2`).
+ *
+ * @param chainId - Numeric chain ID, e.g. a backend vault row's `chain`.
+ * @returns `true` only for `-2`.
+ */
+function isSuiVault(chainId) {
+    return chainId === constants_1.SUI_CHAIN_ID;
+}
+//# sourceMappingURL=utils.js.map

package/lib/core/analytics/app-name.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validate an `appName` slug at SDK boundary points (the `UpshiftSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `UpshiftValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws UpshiftValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+export declare function validateAppName(value: unknown): string;

package/lib/core/analytics/app-name.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAppName = validateAppName;
+const errors_1 = require("../errors");
+/**
+ * Validate an `appName` slug at SDK boundary points (the `UpshiftSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `UpshiftValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws UpshiftValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+function validateAppName(value) {
+    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk/javascript-sdk#app-name';
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `Upshift SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < 3 || trimmed.length > 64) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `Upshift SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `Upshift SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
+    }
+    if (/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `Upshift SDK: \`appName\` looks like a wallet address ("${trimmed}"). Pass an application slug like "acme-trader" — if you are calling initializeSentry directly, note that since v9 the argument order is (config, environment, appName, walletAddress?, apiKey?). ${docsHint}`);
+    }
+    return trimmed;
+}
+//# sourceMappingURL=app-name.js.map

package/lib/core/analytics/chain-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
+export declare function chainIdToTagValue(chainId: number | undefined): string;

package/lib/core/analytics/chain-name.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chainIdToTagValue = chainIdToTagValue;
+const web3_1 = require("../constants/web3");
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
+function chainIdToTagValue(chainId) {
+    if (chainId === undefined || chainId === null || Number.isNaN(chainId)) {
+        return 'unknown';
+    }
+    for (const entry of Object.values(web3_1.SPECIAL_CHAINS)) {
+        if (entry.chainId === chainId) {
+            return slugify(entry.name);
+        }
+    }
+    const network = web3_1.NETWORKS[chainId];
+    if (network) {
+        return slugify(network.name);
+    }
+    return `unknown:${chainId}`;
+}
+function slugify(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+//# sourceMappingURL=chain-name.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
+export declare const SENTRY_DSN = "https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776";
+/**
+ * `appName` slugs of applications Upshift operate themselves.
+ *
+ * Traffic from these is tagged `partner.tier: 'internal'` so that
+ * `partner.tier:unverified` in Sentry already means "external integrator"
+ * before the backend verification endpoint exists. Anything not listed stays
+ * `unverified`; the future verified flow adds a `verified` tier alongside
+ * rather than replacing this list.
+ */
+export declare const FIRST_PARTY_APP_NAMES: ReadonlySet<string>;

package/lib/core/analytics/constants.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_PARTY_APP_NAMES = exports.SENTRY_DSN = void 0;
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
+exports.SENTRY_DSN = 'https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776';
+/**
+ * `appName` slugs of applications Upshift operate themselves.
+ *
+ * Traffic from these is tagged `partner.tier: 'internal'` so that
+ * `partner.tier:unverified` in Sentry already means "external integrator"
+ * before the backend verification endpoint exists. Anything not listed stays
+ * `unverified`; the future verified flow adds a `verified` tier alongside
+ * rather than replacing this list.
+ */
+exports.FIRST_PARTY_APP_NAMES = new Set([
+    'upshift-web-app',
+    'upshift-earn',
+    'upshift-prime',
+    'upshift-cli',
+    'upshift-mcp',
+    // Legacy slugs still emitted by pre-rebrand CLI/MCP installs.
+    'august-cli',
+    'august-mcp',
+]);
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Environment-variable gates for analytics. Pure functions — safe to import
+ * anywhere, no Sentry side effects. Tested directly in `analytics.test.js`.
+ */
+/**
+ * Read a process env var without crashing in browsers or in bundles where
+ * `process.env` is a frozen / proxied object that throws on missing keys.
+ */
+export declare function readEnv(name: string): string | undefined;
+/**
+ * `UPSHIFT_SDK_FORCE_ANALYTICS=1` bypasses the dev/test and localhost gates.
+ * Used by our own smoke-test script and by partners deliberately exercising
+ * telemetry in a non-prod environment.
+ */
+export declare function isAnalyticsForcedOnViaEnv(): boolean;
+/**
+ * `UPSHIFT_SDK_DISABLE_ANALYTICS=1` is the env equivalent of passing
+ * `analytics: { enabled: false }`. Useful when partners can't easily plumb
+ * config through (CI runners, ops scripts).
+ */
+export declare function isAnalyticsDisabledViaEnv(): boolean;
+/**
+ * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
+ * analytics in these environments so partners' local dev runs and Jest suites
+ * don't pollute the production Sentry project.
+ *
+ * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
+ */
+export declare function isNodeDevOrTestEnv(): boolean;
+/**
+ * True when the page is being served from a developer's own machine or private
+ * network.
+ *
+ * The browser counterpart to {@link isNodeDevOrTestEnv}: bundlers strip or
+ * stub `process.env`, so `NODE_ENV` cannot tell a `next dev` tab apart from a
+ * production deploy. The hostname can. Always false in Node, where
+ * `NODE_ENV` is the gate.
+ *
+ * Recognises `localhost` and the `.localhost` TLD (RFC 6761 reserves both for
+ * loopback), mDNS `.local` names, and any loopback / private / link-local IP
+ * literal in either address family. Anything else — including a public host
+ * that merely *contains* one of those names, like `localhost.acme.com` — is
+ * treated as a real deployment, because suppressing a genuine production
+ * origin is the more costly mistake of the two.
+ */
+export declare function isLocalhost(): boolean;

package/lib/core/analytics/env.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Environment-variable gates for analytics. Pure functions — safe to import
+ * anywhere, no Sentry side effects. Tested directly in `analytics.test.js`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readEnv = readEnv;
+exports.isAnalyticsForcedOnViaEnv = isAnalyticsForcedOnViaEnv;
+exports.isAnalyticsDisabledViaEnv = isAnalyticsDisabledViaEnv;
+exports.isNodeDevOrTestEnv = isNodeDevOrTestEnv;
+exports.isLocalhost = isLocalhost;
+/**
+ * Read a process env var without crashing in browsers or in bundles where
+ * `process.env` is a frozen / proxied object that throws on missing keys.
+ */
+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;
+}
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const v = value.toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/**
+ * `UPSHIFT_SDK_FORCE_ANALYTICS=1` bypasses the dev/test and localhost gates.
+ * Used by our own smoke-test script and by partners deliberately exercising
+ * telemetry in a non-prod environment.
+ */
+function isAnalyticsForcedOnViaEnv() {
+    return isTruthyEnv(readEnv('UPSHIFT_SDK_FORCE_ANALYTICS'));
+}
+/**
+ * `UPSHIFT_SDK_DISABLE_ANALYTICS=1` is the env equivalent of passing
+ * `analytics: { enabled: false }`. Useful when partners can't easily plumb
+ * config through (CI runners, ops scripts).
+ */
+function isAnalyticsDisabledViaEnv() {
+    return isTruthyEnv(readEnv('UPSHIFT_SDK_DISABLE_ANALYTICS'));
+}
+/**
+ * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
+ * analytics in these environments so partners' local dev runs and Jest suites
+ * don't pollute the production Sentry project.
+ *
+ * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
+ */
+function isNodeDevOrTestEnv() {
+    const env = readEnv('NODE_ENV');
+    return env === 'development' || env === 'test';
+}
+/** Dotted-quad IPv4 literal. Anchored, so `10.acme.com` is not an address. */
+const IPV4_LITERAL = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * True for an IPv4 literal that cannot be a public production origin: loopback
+ * (`127.0.0.0/8` — `127.0.0.1` is only the most common of 16.7M), the
+ * "this host" block (`0.0.0.0/8`), the three RFC 1918 private ranges, and
+ * link-local (`169.254.0.0/16`).
+ *
+ * Ranges are checked by octet rather than by string prefix on purpose: a
+ * `startsWith('10.')` test both misses `172.20.0.2` (a default Docker bridge
+ * address, and a very ordinary way to reach a container) and misfires on a
+ * public host that merely begins with those digits.
+ */
+function isPrivateIpv4(hostname) {
+    const octets = IPV4_LITERAL.exec(hostname);
+    if (!octets)
+        return false;
+    const [a, b, c, d] = octets.slice(1).map(Number);
+    // The regex counts digits, not values, so an out-of-range quad still matches
+    // its shape. `127.0.0.999` is not an address — the URL parser rejects it
+    // rather than handing it over as a `hostname` — so it is a name, and names
+    // that are not the reserved ones are treated as deployed.
+    if (a > 255 || b > 255 || c > 255 || d > 255)
+        return false;
+    return (a === 127 ||
+        a === 0 ||
+        a === 10 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254));
+}
+/**
+ * True for an IPv6 literal that cannot be a public production origin:
+ * loopback (`::1`, in either notation), the unspecified address, an
+ * IPv4-mapped private address, unique-local (`fc00::/7`) and link-local
+ * (`fe80::/10`).
+ *
+ * `hostname` carries the brackets for an IPv6 host — `http://[::1]:3000/`
+ * yields `[::1]`, per the URL standard's host serialization — so they are
+ * stripped before matching.
+ */
+function isLocalIpv6(hostname) {
+    const host = hostname.replace(/^\[/, '').replace(/\]$/, '');
+    if (!host.includes(':'))
+        return false;
+    if (host === '::1' || host === '::')
+        return true;
+    if (/^(?:0{1,4}:){7}0{0,3}1$/.test(host))
+        return true;
+    if (host.startsWith('::ffff:'))
+        return isPrivateIpv4(host.slice(7));
+    return /^f[cd]/.test(host) || /^fe[89ab]/.test(host);
+}
+/**
+ * True when the page is being served from a developer's own machine or private
+ * network.
+ *
+ * The browser counterpart to {@link isNodeDevOrTestEnv}: bundlers strip or
+ * stub `process.env`, so `NODE_ENV` cannot tell a `next dev` tab apart from a
+ * production deploy. The hostname can. Always false in Node, where
+ * `NODE_ENV` is the gate.
+ *
+ * Recognises `localhost` and the `.localhost` TLD (RFC 6761 reserves both for
+ * loopback), mDNS `.local` names, and any loopback / private / link-local IP
+ * literal in either address family. Anything else — including a public host
+ * that merely *contains* one of those names, like `localhost.acme.com` — is
+ * treated as a real deployment, because suppressing a genuine production
+ * origin is the more costly mistake of the two.
+ */
+function isLocalhost() {
+    try {
+        if (typeof window !== 'undefined' && window.location) {
+            // Hostnames are case-insensitive; browsers normalize, other runtimes
+            // hosting a `window` shim may not.
+            const hostname = String(window.location.hostname).toLowerCase();
+            return (hostname === 'localhost' ||
+                hostname.endsWith('.localhost') ||
+                hostname.endsWith('.local') ||
+                isPrivateIpv4(hostname) ||
+                isLocalIpv6(hostname));
+        }
+    }
+    catch {
+        // Some embedded/sandboxed runtimes throw on `window.location`. Not local.
+    }
+    return false;
+}
+//# sourceMappingURL=env.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * Analytics module for SDK usage tracking via Sentry.
+ *
+ * Features:
+ * - User identification (API key hash, wallet, domain, fingerprint, session)
+ * - Method call tracking with timing, classified by {@link METHOD_CATEGORIES}
+ * - Application attribution (`app.name`, `partner.id`, `partner.tier`,
+ *   `sdk.surface`) on every event and span
+ * - API response time tracking
+ * - Chain/network usage distribution
+ *
+ * @example
+ * ```typescript
+ * // Analytics enabled by default
+ * const sdk = new UpshiftSDK({
+ *   appName: 'acme-trader',
+ *   providers: { 1: 'https://...' },
+ *   keys: { upshift: '...' },
+ * });
+ *
+ * // Opt-out of analytics
+ * const sdk = new UpshiftSDK({
+ *   appName: 'acme-trader',
+ *   providers: { 1: 'https://...' },
+ *   keys: { upshift: '...' },
+ *   analytics: { enabled: false },
+ * });
+ * ```
+ */
+export type { IAnalyticsConfig, IUserIdentity, IMethodCallMetrics, } from './types';
+export { hashApiKey, getSessionId, generateFingerprint, createUserIdentity, getUserId, } from './user-identity';
+export { initializeSentry, updateUser, clearUser, isAnalyticsEnabled, getSentry, resetAnalytics, captureSdkException, } from './sentry';
+export { getSentrySDK, getSentryRuntime } from './sentry-runtime';
+export { readEnv, isAnalyticsDisabledViaEnv, isAnalyticsForcedOnViaEnv, isNodeDevOrTestEnv, } from './env';
+export { trackApiCall, trackNetworkSwitch, trackKeyVerification, getCacheStats, resetCacheStats, } from './metrics';
+export { sanitizeArgs, sanitizeObject, computeArgShape } from './sanitize';
+export { withMethodTracking, withSyncMethodTracking, instrumentClass, } from './instrumentation';
+export { METHOD_CATEGORIES, getMethodCategory, type MethodCategory, } from './method-taxonomy';
+export { chainIdToTagValue } from './chain-name';