perp-cli 0.3.3

package/dist/__tests__/funding-rates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/funding-rates.test.js

@@ -0,0 +1,342 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+/**
+ * Tests for the funding-rates module.
+ *
+ * These test the core comparison/normalization logic using mocked API responses.
+ * Integration tests that hit real APIs live in integration/.
+ */
+// Mock fetch globally before importing the module
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+// Import after mocking fetch
+const { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS } = await import("../funding-rates.js");
+const { invalidateCache } = await import("../cache.js");
+// ── Helpers to build mock API responses ──
+function makePacificaResponse(rates) {
+    return { data: rates };
+}
+function makeHyperliquidResponse(assets, ctxs) {
+    return [{ universe: assets }, ctxs];
+}
+function makeLighterResponse(details, fundingRates) {
+    return {
+        details: { order_book_details: details },
+        funding: { funding_rates: fundingRates.map(fr => ({ exchange: "lighter", ...fr })) },
+    };
+}
+function setupMockFetch(opts) {
+    mockFetch.mockImplementation(async (url, init) => {
+        const urlStr = typeof url === "string" ? url : url.toString();
+        // Pacifica
+        if (urlStr.includes("pacifica.fi")) {
+            if (opts.pacError)
+                throw new Error("Pacifica API error");
+            return {
+                json: async () => makePacificaResponse(opts.pac ?? []),
+            };
+        }
+        // Hyperliquid
+        if (urlStr.includes("hyperliquid.xyz")) {
+            if (opts.hlError)
+                throw new Error("HL API error");
+            const hl = opts.hl ?? { assets: [], ctxs: [] };
+            return {
+                json: async () => makeHyperliquidResponse(hl.assets, hl.ctxs),
+            };
+        }
+        // Lighter - two endpoints
+        if (urlStr.includes("zklighter") && urlStr.includes("orderBookDetails")) {
+            if (opts.ltError)
+                throw new Error("Lighter API error");
+            const lt = opts.lt ?? { details: [], funding: [] };
+            return {
+                json: async () => ({ order_book_details: lt.details }),
+            };
+        }
+        if (urlStr.includes("zklighter") && urlStr.includes("funding-rates")) {
+            if (opts.ltError)
+                throw new Error("Lighter API error");
+            const lt = opts.lt ?? { details: [], funding: [] };
+            return {
+                json: async () => ({ funding_rates: lt.funding.map(fr => ({ exchange: "lighter", ...fr })) }),
+            };
+        }
+        throw new Error(`Unexpected fetch: ${urlStr}`);
+    });
+}
+beforeEach(() => {
+    mockFetch.mockReset();
+    invalidateCache();
+});
+// ──────────────────────────────────────────────
+// TOP_SYMBOLS
+// ──────────────────────────────────────────────
+describe("TOP_SYMBOLS", () => {
+    it("includes major crypto assets", () => {
+        expect(TOP_SYMBOLS).toContain("BTC");
+        expect(TOP_SYMBOLS).toContain("ETH");
+        expect(TOP_SYMBOLS).toContain("SOL");
+    });
+    it("has at least 10 symbols", () => {
+        expect(TOP_SYMBOLS.length).toBeGreaterThanOrEqual(10);
+    });
+});
+// ──────────────────────────────────────────────
+// fetchAllFundingRates
+// ──────────────────────────────────────────────
+describe("fetchAllFundingRates", () => {
+    it("fetches from all 3 exchanges in parallel and compares", async () => {
+        setupMockFetch({
+            pac: [
+                { symbol: "BTC", funding: 0.0008, mark: 60000 },
+                { symbol: "ETH", funding: 0.0004, mark: 3000 },
+            ],
+            hl: {
+                assets: [{ name: "BTC" }, { name: "ETH" }],
+                ctxs: [
+                    { funding: 0.0002, markPx: 60100 },
+                    { funding: 0.0001, markPx: 3010 },
+                ],
+            },
+            lt: {
+                details: [
+                    { market_id: 1, symbol: "BTC", last_trade_price: 59900 },
+                    { market_id: 2, symbol: "ETH", last_trade_price: 2990 },
+                ],
+                funding: [
+                    { market_id: 1, rate: 0.0005 },
+                    { market_id: 2, rate: 0.0002 },
+                ],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        expect(snapshot.timestamp).toBeTruthy();
+        expect(snapshot.exchangeStatus.pacifica).toBe("ok");
+        expect(snapshot.exchangeStatus.hyperliquid).toBe("ok");
+        expect(snapshot.exchangeStatus.lighter).toBe("ok");
+        expect(snapshot.symbols.length).toBe(2);
+        // Should be sorted by spread descending
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        expect(btc).toBeTruthy();
+        expect(btc.rates.length).toBe(3);
+        expect(btc.maxSpreadAnnual).toBeGreaterThan(0);
+    });
+    it("identifies correct long/short direction", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "BTC", funding: 0.001, mark: 60000 }],
+            hl: {
+                assets: [{ name: "BTC" }],
+                ctxs: [{ funding: 0.00005, markPx: 60100 }],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        expect(btc).toBeTruthy();
+        // PAC funding is higher -> short PAC (get paid), long HL (pay less)
+        // HL rate per hour = 0.00005, PAC rate per hour = 0.001
+        // HL hourly < PAC hourly -> long on HL, short on PAC
+        expect(btc.longExchange).toBe("hyperliquid");
+        expect(btc.shortExchange).toBe("pacifica");
+    });
+    it("filters by symbols when specified", async () => {
+        setupMockFetch({
+            pac: [
+                { symbol: "BTC", funding: 0.0008, mark: 60000 },
+                { symbol: "ETH", funding: 0.0004, mark: 3000 },
+            ],
+            hl: {
+                assets: [{ name: "BTC" }, { name: "ETH" }],
+                ctxs: [
+                    { funding: 0.0001, markPx: 60100 },
+                    { funding: 0.00005, markPx: 3010 },
+                ],
+            },
+        });
+        const snapshot = await fetchAllFundingRates({ symbols: ["BTC"] });
+        expect(snapshot.symbols.length).toBe(1);
+        expect(snapshot.symbols[0].symbol).toBe("BTC");
+    });
+    it("filters by minimum spread", async () => {
+        setupMockFetch({
+            pac: [
+                { symbol: "BTC", funding: 0.001, mark: 60000 }, // high spread
+                { symbol: "ETH", funding: 0.00011, mark: 3000 }, // tiny spread
+            ],
+            hl: {
+                assets: [{ name: "BTC" }, { name: "ETH" }],
+                ctxs: [
+                    { funding: 0.00005, markPx: 60100 },
+                    { funding: 0.0001, markPx: 3010 },
+                ],
+            },
+        });
+        const snapshot = await fetchAllFundingRates({ minSpread: 50 });
+        // Only BTC should have a spread > 50%
+        for (const s of snapshot.symbols) {
+            expect(s.maxSpreadAnnual).toBeGreaterThanOrEqual(50);
+        }
+    });
+    it("requires at least 2 exchanges for a symbol", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "UNIQUE_PAC", funding: 0.001, mark: 100 }],
+            hl: { assets: [], ctxs: [] },
+        });
+        const snapshot = await fetchAllFundingRates();
+        // UNIQUE_PAC only on pacifica -> should be excluded
+        const unique = snapshot.symbols.find(s => s.symbol === "UNIQUE_PAC");
+        expect(unique).toBeUndefined();
+    });
+    it("handles exchange errors gracefully", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "BTC", funding: 0.0008, mark: 60000 }],
+            hlError: true,
+            lt: {
+                details: [{ market_id: 1, symbol: "BTC", last_trade_price: 59900 }],
+                funding: [{ market_id: 1, rate: 0.0005 }],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        expect(snapshot.exchangeStatus.hyperliquid).toBe("error");
+        expect(snapshot.exchangeStatus.pacifica).toBe("ok");
+        expect(snapshot.exchangeStatus.lighter).toBe("ok");
+        // BTC should still be available (2 exchanges: pac + lt)
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        expect(btc).toBeTruthy();
+        expect(btc.rates.length).toBe(2);
+    });
+    it("prefers HL mark price as most liquid", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "BTC", funding: 0.0008, mark: 59000 }],
+            hl: {
+                assets: [{ name: "BTC" }],
+                ctxs: [{ funding: 0.0001, markPx: 60000 }],
+            },
+            lt: {
+                details: [{ market_id: 1, symbol: "BTC", last_trade_price: 59500 }],
+                funding: [{ market_id: 1, rate: 0.0005 }],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        expect(btc.bestMarkPrice).toBe(60000); // HL price preferred
+    });
+    it("estimates positive hourly income for favorable spreads", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "BTC", funding: 0.002, mark: 60000 }],
+            hl: {
+                assets: [{ name: "BTC" }],
+                ctxs: [{ funding: -0.0001, markPx: 60000 }],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        // Large positive spread -> positive estimated income
+        expect(btc.estHourlyIncomeUsd).toBeGreaterThan(0);
+    });
+    it("returns results sorted by spread descending", async () => {
+        setupMockFetch({
+            pac: [
+                { symbol: "SMALL", funding: 0.0002, mark: 100 },
+                { symbol: "BIG", funding: 0.003, mark: 200 },
+            ],
+            hl: {
+                assets: [{ name: "SMALL" }, { name: "BIG" }],
+                ctxs: [
+                    { funding: 0.0001, markPx: 100 },
+                    { funding: 0.00005, markPx: 200 },
+                ],
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        if (snapshot.symbols.length >= 2) {
+            expect(snapshot.symbols[0].maxSpreadAnnual).toBeGreaterThanOrEqual(snapshot.symbols[1].maxSpreadAnnual);
+        }
+    });
+});
+// ──────────────────────────────────────────────
+// fetchSymbolFundingRates
+// ──────────────────────────────────────────────
+describe("fetchSymbolFundingRates", () => {
+    it("returns comparison for a single symbol", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "ETH", funding: 0.0004, mark: 3000 }],
+            hl: {
+                assets: [{ name: "ETH" }, { name: "BTC" }],
+                ctxs: [
+                    { funding: 0.0001, markPx: 3010 },
+                    { funding: 0.0002, markPx: 60000 },
+                ],
+            },
+        });
+        const result = await fetchSymbolFundingRates("ETH");
+        expect(result).toBeTruthy();
+        expect(result.symbol).toBe("ETH");
+        expect(result.rates.length).toBe(2);
+    });
+    it("returns null when symbol not found on 2+ exchanges", async () => {
+        setupMockFetch({
+            pac: [],
+            hl: {
+                assets: [{ name: "NOEXIST" }],
+                ctxs: [{ funding: 0.0001, markPx: 100 }],
+            },
+        });
+        const result = await fetchSymbolFundingRates("NOEXIST");
+        expect(result).toBeNull();
+    });
+    it("is case-insensitive", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "SOL", funding: 0.0005, mark: 150 }],
+            hl: {
+                assets: [{ name: "SOL" }],
+                ctxs: [{ funding: 0.0001, markPx: 151 }],
+            },
+        });
+        const result = await fetchSymbolFundingRates("sol");
+        expect(result).toBeTruthy();
+        expect(result.symbol).toBe("SOL");
+    });
+});
+// ──────────────────────────────────────────────
+// 3-DEX direction logic
+// ──────────────────────────────────────────────
+describe("3-DEX direction logic", () => {
+    it("picks correct long/short when lighter has best rate", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "BTC", funding: 0.00006, mark: 60000 }], // hourly = 0.00006
+            hl: {
+                assets: [{ name: "BTC" }],
+                ctxs: [{ funding: 0.0002, markPx: 60100 }], // hourly = 0.0002 (highest)
+            },
+            lt: {
+                details: [{ market_id: 1, symbol: "BTC", last_trade_price: 59900 }],
+                funding: [{ market_id: 1, rate: 0.00001 }], // 8h rate, hourly = 0.00001/8 (lowest)
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        const btc = snapshot.symbols.find(s => s.symbol === "BTC");
+        expect(btc).toBeTruthy();
+        // Lighter has lowest hourly rate (0.00001/8) -> long on lighter
+        // HL has highest hourly rate (0.0002) -> short on HL
+        expect(btc.longExchange).toBe("lighter");
+        expect(btc.shortExchange).toBe("hyperliquid");
+    });
+    it("picks pacifica as short when it has highest rate", async () => {
+        setupMockFetch({
+            pac: [{ symbol: "ETH", funding: 0.0005, mark: 3000 }], // hourly = 0.0005 (highest)
+            hl: {
+                assets: [{ name: "ETH" }],
+                ctxs: [{ funding: 0.0001, markPx: 3010 }], // hourly = 0.0001 (mid)
+            },
+            lt: {
+                details: [{ market_id: 2, symbol: "ETH", last_trade_price: 2990 }],
+                funding: [{ market_id: 2, rate: 0.000025 }], // 8h rate, hourly = 0.000025/8 (lowest)
+            },
+        });
+        const snapshot = await fetchAllFundingRates();
+        const eth = snapshot.symbols.find(s => s.symbol === "ETH");
+        expect(eth).toBeTruthy();
+        expect(eth.shortExchange).toBe("pacifica");
+        expect(eth.longExchange).toBe("lighter");
+    });
+});

package/dist/__tests__/funding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/funding.test.js

@@ -0,0 +1,173 @@
+import { describe, it, expect } from "vitest";
+import { getFundingHours, toHourlyRate, annualizeRate, computeAnnualSpread, estimateHourlyFunding, } from "../funding.js";
+// ──────────────────────────────────────────────
+// getFundingHours
+// ──────────────────────────────────────────────
+describe("getFundingHours", () => {
+    it("returns 1 for hyperliquid", () => {
+        expect(getFundingHours("hyperliquid")).toBe(1);
+    });
+    it("returns 1 for pacifica", () => {
+        expect(getFundingHours("pacifica")).toBe(1);
+    });
+    it("returns 8 for lighter", () => {
+        expect(getFundingHours("lighter")).toBe(8);
+    });
+    it("defaults to 1 for unknown exchanges (main exchanges are hourly)", () => {
+        expect(getFundingHours("binance")).toBe(1);
+        expect(getFundingHours("unknown_dex")).toBe(1);
+    });
+    it("is case-insensitive", () => {
+        expect(getFundingHours("Hyperliquid")).toBe(1);
+        expect(getFundingHours("PACIFICA")).toBe(1);
+        expect(getFundingHours("Lighter")).toBe(8);
+    });
+});
+// ──────────────────────────────────────────────
+// toHourlyRate
+// ──────────────────────────────────────────────
+describe("toHourlyRate", () => {
+    it("divides by 1 for hyperliquid (rate is already per-hour)", () => {
+        const hourly = toHourlyRate(0.0001, "hyperliquid");
+        expect(hourly).toBeCloseTo(0.0001);
+    });
+    it("divides by 1 for pacifica (rate is already per-hour)", () => {
+        const hourly = toHourlyRate(0.0001, "pacifica");
+        expect(hourly).toBeCloseTo(0.0001);
+    });
+    it("divides by 8 for lighter (API returns 8h rate)", () => {
+        const hourly = toHourlyRate(0.0002, "lighter");
+        expect(hourly).toBeCloseTo(0.0002 / 8);
+    });
+    it("divides by 1 for unknown exchanges (default)", () => {
+        const hourly = toHourlyRate(0.0001, "someExchange");
+        expect(hourly).toBeCloseTo(0.0001);
+    });
+    it("handles zero rate", () => {
+        expect(toHourlyRate(0, "hyperliquid")).toBe(0);
+        expect(toHourlyRate(0, "pacifica")).toBe(0);
+    });
+    it("handles negative rate", () => {
+        const hourly = toHourlyRate(-0.0001, "pacifica");
+        expect(hourly).toBeCloseTo(-0.0001);
+    });
+});
+// ──────────────────────────────────────────────
+// annualizeRate
+// ──────────────────────────────────────────────
+describe("annualizeRate", () => {
+    it("annualizes hyperliquid rate (hourly * 8760 * 100)", () => {
+        // rate = 0.0001 per hour → annualized = 0.0001 * 8760 * 100 = 87.6%
+        const annual = annualizeRate(0.0001, "hyperliquid");
+        expect(annual).toBeCloseTo(87.6);
+    });
+    it("annualizes pacifica rate (hourly * 8760 * 100)", () => {
+        // rate = 0.0001 per hour → annualized = 0.0001 * 8760 * 100 = 87.6%
+        const annual = annualizeRate(0.0001, "pacifica");
+        expect(annual).toBeCloseTo(87.6);
+    });
+    it("produces same annualized rate for equivalent rates across exchanges", () => {
+        // All exchanges are hourly now, so same rate = same annualized
+        const hlAnnual = annualizeRate(0.0001, "hyperliquid");
+        const pacAnnual = annualizeRate(0.0001, "pacifica");
+        expect(hlAnnual).toBeCloseTo(pacAnnual);
+    });
+    it("handles zero rate", () => {
+        expect(annualizeRate(0, "hyperliquid")).toBe(0);
+        expect(annualizeRate(0, "pacifica")).toBe(0);
+    });
+    it("handles negative rates", () => {
+        const annual = annualizeRate(-0.0001, "hyperliquid");
+        expect(annual).toBeCloseTo(-87.6);
+    });
+});
+// ──────────────────────────────────────────────
+// computeAnnualSpread
+// ──────────────────────────────────────────────
+describe("computeAnnualSpread", () => {
+    it("computes spread between two different exchanges", () => {
+        // HL rate 0.0002/h, pacifica rate 0.0001/h → spread = 0.0001/h * 8760 * 100 = 87.6%
+        const spread = computeAnnualSpread(0.0002, "hyperliquid", 0.0001, "pacifica");
+        expect(spread).toBeCloseTo(87.6);
+    });
+    it("returns 0 when rates are identical", () => {
+        // Both hourly, same rate
+        const spread = computeAnnualSpread(0.0001, "hyperliquid", 0.0001, "pacifica");
+        expect(spread).toBeCloseTo(0);
+    });
+    it("returns absolute value regardless of which rate is higher", () => {
+        const spread1 = computeAnnualSpread(0.0003, "hyperliquid", 0.0001, "hyperliquid");
+        const spread2 = computeAnnualSpread(0.0001, "hyperliquid", 0.0003, "hyperliquid");
+        expect(spread1).toBeCloseTo(spread2);
+        expect(spread1).toBeGreaterThan(0);
+    });
+    it("computes spread between pacifica (1h) and lighter (8h)", () => {
+        // pacifica raw 0.000125 → hourly = 0.000125
+        // lighter raw 0.0000625 → hourly = 0.0000625/8 = 0.0000078125
+        // diff: |0.000125 - 0.0000078125| = 0.0001171875/h * 8760 * 100 = 102.66%
+        const spread = computeAnnualSpread(0.000125, "pacifica", 0.0000625, "lighter");
+        expect(spread).toBeCloseTo(102.66, 1);
+    });
+    it("handles zero rates", () => {
+        const spread = computeAnnualSpread(0, "hyperliquid", 0, "pacifica");
+        expect(spread).toBe(0);
+    });
+    it("handles one zero rate", () => {
+        const spread = computeAnnualSpread(0.0001, "hyperliquid", 0, "pacifica");
+        // hourly diff = 0.0001, spread = 0.0001 * 8760 * 100 = 87.6%
+        expect(spread).toBeCloseTo(87.6);
+    });
+    it("handles negative rates (one exchange paying, other receiving)", () => {
+        // HL pays +0.0001/h, pacifica -0.0001/h
+        // diff = |0.0001 - (-0.0001)| = 0.0002/h * 8760 * 100 = 175.2%
+        const spread = computeAnnualSpread(0.0001, "hyperliquid", -0.0001, "pacifica");
+        expect(spread).toBeCloseTo(175.2);
+    });
+});
+// ──────────────────────────────────────────────
+// estimateHourlyFunding
+// ──────────────────────────────────────────────
+describe("estimateHourlyFunding", () => {
+    it("long pays positive funding (positive rate)", () => {
+        // rate = 0.0001/h (HL), position = $10000
+        // hourly payment = 0.0001 * 10000 * 1 = $1
+        const payment = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "long");
+        expect(payment).toBeCloseTo(1);
+    });
+    it("short receives positive funding (positive rate)", () => {
+        // rate = 0.0001/h (HL), position = $10000
+        // hourly payment = 0.0001 * 10000 * (-1) = -$1 (receiving)
+        const payment = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "short");
+        expect(payment).toBeCloseTo(-1);
+    });
+    it("long receives negative funding (negative rate)", () => {
+        // rate = -0.0001/h, position = $10000
+        // hourly = -0.0001 * 10000 * 1 = -$1 (receiving)
+        const payment = estimateHourlyFunding(-0.0001, "hyperliquid", 10000, "long");
+        expect(payment).toBeCloseTo(-1);
+    });
+    it("short pays negative funding (negative rate)", () => {
+        // rate = -0.0001/h, position = $10000
+        // hourly = -0.0001 * 10000 * (-1) = $1 (paying)
+        const payment = estimateHourlyFunding(-0.0001, "hyperliquid", 10000, "short");
+        expect(payment).toBeCloseTo(1);
+    });
+    it("uses hourly rate directly for pacifica", () => {
+        // rate = 0.0001/h (pacifica), position = $10000
+        // long pays: 0.0001 * 10000 = $1
+        const payment = estimateHourlyFunding(0.0001, "pacifica", 10000, "long");
+        expect(payment).toBeCloseTo(1);
+    });
+    it("returns 0 for zero funding rate", () => {
+        expect(estimateHourlyFunding(0, "hyperliquid", 10000, "long")).toBeCloseTo(0);
+        expect(estimateHourlyFunding(0, "pacifica", 10000, "short")).toBeCloseTo(0);
+    });
+    it("returns 0 for zero position size", () => {
+        expect(estimateHourlyFunding(0.0001, "hyperliquid", 0, "long")).toBe(0);
+    });
+    it("scales linearly with position size", () => {
+        const small = estimateHourlyFunding(0.0001, "hyperliquid", 1000, "long");
+        const large = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "long");
+        expect(large).toBeCloseTo(small * 10);
+    });
+});

package/dist/__tests__/gap-logic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/gap-logic.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+function computeGap(symbol, pacPrice, hlPrice) {
+    if (pacPrice <= 0 || hlPrice <= 0)
+        return null;
+    const mid = (pacPrice + hlPrice) / 2;
+    const gapPct = ((pacPrice - hlPrice) / mid) * 100;
+    return {
+        symbol,
+        pacPrice,
+        hlPrice,
+        gapPct,
+        direction: pacPrice > hlPrice ? "PAC>HL" : "HL>PAC",
+    };
+}
+describe("Price gap computation", () => {
+    it("positive gap when PAC > HL", () => {
+        const gap = computeGap("BTC", 100100, 99900);
+        expect(gap).not.toBeNull();
+        expect(gap.gapPct).toBeCloseTo(0.2, 1);
+        expect(gap.direction).toBe("PAC>HL");
+    });
+    it("negative gap when HL > PAC", () => {
+        const gap = computeGap("ETH", 3490, 3510);
+        expect(gap).not.toBeNull();
+        expect(gap.gapPct).toBeLessThan(0);
+        expect(gap.direction).toBe("HL>PAC");
+    });
+    it("zero gap when equal", () => {
+        const gap = computeGap("SOL", 150, 150);
+        expect(gap).not.toBeNull();
+        expect(gap.gapPct).toBe(0);
+    });
+    it("returns null for zero prices", () => {
+        expect(computeGap("X", 0, 100)).toBeNull();
+        expect(computeGap("X", 100, 0)).toBeNull();
+    });
+    it("handles large gaps", () => {
+        const gap = computeGap("MEME", 1.0, 0.5);
+        expect(gap).not.toBeNull();
+        // (1.0 - 0.5) / 0.75 * 100 ≈ 66.67%
+        expect(gap.gapPct).toBeCloseTo(66.67, 1);
+    });
+});

package/dist/__tests__/hip3-dex.test.d.ts

@@ -0,0 +1 @@
+export {};