lpsignal 0.1.0

package/dist/stream.js

@@ -0,0 +1,310 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import WebSocket from 'ws';
+import { LPSignalError } from './client.js';
+export class MemoryLastIdStore {
+    id = null;
+    async load() { return this.id; }
+    async save(lastId) { this.id = lastId; }
+}
+/** A small JSON file, replaced atomically (temp file + rename) so a crash never leaves half a file. */
+export class FileLastIdStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async load() {
+        let text;
+        try {
+            text = await readFile(this.path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+        const id = JSON.parse(text).lastId;
+        if (typeof id !== 'string' || !/^\d+$/.test(id))
+            throw new Error(`${this.path}: no valid lastId`);
+        return id;
+    }
+    async save(lastId) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp`;
+        await writeFile(tmp, JSON.stringify({ lastId }));
+        await rename(tmp, this.path);
+    }
+}
+/**
+ * Live signals in id order, with no gaps across disconnects, outages and restarts.
+ *
+ * The server replays the last 24 hours on `?since=<id>`. Before every connection this stream first fetches everything
+ * newer than its position over REST, repeating until a pass finds nothing new, so an outage of any length is filled
+ * and the socket opens seconds after the last fetch. Anything at or below the position is dropped, so within one
+ * running process each signal reaches the handler once; across a crash the last one may be offered again.
+ */
+export class SignalStream {
+    opts;
+    store;
+    socketFactory;
+    lastId = null;
+    queue = Promise.resolve();
+    running = false;
+    socket = null;
+    loopDone = null;
+    wake = null;
+    starting = null;
+    stopping = null;
+    /** the first-run starting point, chosen once and kept until it is saved (a retry must not pick a newer one) */
+    anchor = null;
+    constructor(options) {
+        if (!options.client.apiKey)
+            throw new Error('SignalStream: the client needs an API key (the stream is for paid plans)');
+        if (options.since !== undefined && !/^\d+$/.test(options.since))
+            throw new Error('SignalStream: since must be a signal id');
+        this.opts = { pingIntervalMs: 30_000, openTimeoutMs: 15_000, minBackoffMs: 1_000, maxBackoffMs: 30_000, ...options };
+        this.store = options.store ?? new MemoryLastIdStore();
+        this.socketFactory = options.socketFactory
+            ?? ((url, headers) => new WebSocket(url, {
+                handshakeTimeout: this.opts.openTimeoutMs,
+                ...options.wsOptions,
+                headers: { ...options.wsOptions?.headers, ...headers },
+            }));
+    }
+    /** Id of the last signal handed to onSignal (null before the first connection). */
+    get position() { return this.lastId; }
+    /**
+     * Loads the saved position and starts in the background; call stop() to end. Calling it while running is a no-op;
+     * during a stop() it starts once the stop has finished. After a `fatal` event, call stop() before starting again.
+     */
+    start() {
+        if (this.stopping)
+            return this.stopping.then(() => this.start());
+        // claimed synchronously: concurrent calls share one start, and a stop() during load() cancels it
+        this.starting ??= (async () => {
+            this.running = true;
+            try {
+                const saved = await this.store.load();
+                if (!this.running)
+                    return;
+                this.lastId = saved ?? this.opts.since ?? null;
+                this.loopDone = this.loop();
+            }
+            catch (e) {
+                this.running = false;
+                this.starting = null;
+                throw e;
+            }
+        })();
+        return this.starting;
+    }
+    /**
+     * Closes the socket and waits for the signal being handled (if any). The stream can be started again.
+     * Don't await it from inside onSignal: it would wait for itself.
+     */
+    stop() {
+        // every caller waits for the same, complete shutdown
+        this.stopping ??= (async () => {
+            this.running = false;
+            this.socket?.close(1000);
+            this.wake?.();
+            await this.starting?.catch(() => undefined);
+            await this.loopDone;
+            await this.queue;
+            this.starting = null;
+            this.loopDone = null;
+        })().finally(() => { this.stopping = null; });
+        return this.stopping;
+    }
+    emit(e) {
+        try {
+            this.opts.onEvent?.(e);
+        }
+        catch { /* a listener must not break the stream */ }
+    }
+    fatal(error) {
+        this.running = false;
+        this.emit({ type: 'fatal', error });
+    }
+    async loop() {
+        let backoff = this.opts.minBackoffMs;
+        while (this.running) {
+            let healthy = false;
+            try {
+                await this.catchUp();
+                if (this.running)
+                    healthy = await this.connectOnce();
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                if (err instanceof LPSignalError && err.status === 401)
+                    this.fatal(err);
+                else
+                    this.emit({ type: 'error', error: err });
+            }
+            if (!this.running)
+                break;
+            backoff = healthy ? this.opts.minBackoffMs : Math.min(backoff * 2, this.opts.maxBackoffMs);
+            await new Promise((r) => { const t = setTimeout(r, backoff); this.wake = () => { clearTimeout(t); r(); }; });
+            this.wake = null;
+        }
+    }
+    /** Establish a position (first run) or fetch everything after it over REST. */
+    async catchUp() {
+        if (this.lastId === null) {
+            // nothing is consumed until the starting point is saved: a restart must resume from this same point
+            this.anchor ??= (await this.opts.client.signals({ limit: 1 })).signals[0]?.id ?? '0';
+            await this.store.save(this.anchor);
+            this.lastId = this.anchor;
+            this.emit({ type: 'anchored', lastId: this.lastId });
+        }
+        // repeat until a pass finds nothing: a long backlog can take longer than the server's 24h replay window, and
+        // whatever was created meanwhile must come from REST too, or the socket would skip it
+        let delivered = 0;
+        for (;;) {
+            const batch = await this.opts.client.signalsAfter(this.lastId);
+            if (!batch.length || !this.running)
+                break;
+            for (const s of batch) {
+                if (!this.running)
+                    return;
+                if (await this.deliver(s, 'rest'))
+                    delivered++;
+            }
+        }
+        if (delivered)
+            this.emit({ type: 'caught_up', delivered });
+    }
+    /** One connection's life. Resolves when it closes; true when it went live. */
+    connectOnce() {
+        return new Promise((resolve) => {
+            const url = `${this.opts.client.streamUrl}?since=${this.lastId}`;
+            this.emit({ type: 'connecting', url });
+            let ws;
+            try {
+                ws = this.socketFactory(url, { authorization: `Bearer ${this.opts.client.apiKey}` });
+            }
+            catch (e) {
+                this.emit({ type: 'error', error: e });
+                resolve(false);
+                return;
+            }
+            this.socket = ws;
+            const conn = { failed: false, live: false, opened: false, done: false };
+            let alive = true;
+            let pinger = null;
+            const finish = () => {
+                if (conn.done)
+                    return;
+                conn.done = true;
+                clearTimeout(opener);
+                if (pinger)
+                    clearInterval(pinger);
+                if (this.socket === ws)
+                    this.socket = null;
+                // let this connection's queued frames finish before the next connection starts
+                void this.queue.then(() => resolve(conn.live && !conn.failed));
+            };
+            // a peer that accepts TCP but never answers the upgrade must not stall the stream
+            const opener = setTimeout(() => {
+                if (conn.opened)
+                    return;
+                this.emit({ type: 'error', error: new Error(`stream did not open within ${this.opts.openTimeoutMs} ms`) });
+                try {
+                    ws.terminate();
+                }
+                catch { /* already gone */ }
+                finish();
+            }, this.opts.openTimeoutMs);
+            ws.on('unexpected-response', (_req, res) => {
+                const code = res?.statusCode ?? 0;
+                if (code === 401)
+                    this.fatal(new Error('stream refused (401): the API key is invalid or was replaced'));
+                else if (code === 402)
+                    this.fatal(new Error('stream refused (402): the plan does not include the stream'));
+                else
+                    this.emit({ type: 'error', error: new Error(`stream refused (${code})${code === 429 ? ': too many connections for this key' : ''}`) });
+                try {
+                    ws.terminate();
+                }
+                catch { /* already gone */ }
+            });
+            ws.on('open', () => {
+                conn.opened = true;
+                clearTimeout(opener);
+                if (!this.running) {
+                    ws.close(1000);
+                    return;
+                }
+                this.emit({ type: 'connected' });
+                pinger = setInterval(() => {
+                    // a half-open TCP connection is only found by asking
+                    if (!alive) {
+                        ws.terminate();
+                        return;
+                    }
+                    alive = false;
+                    try {
+                        ws.ping();
+                    }
+                    catch { /* close follows */ }
+                }, this.opts.pingIntervalMs);
+            });
+            ws.on('pong', () => { alive = true; });
+            ws.on('message', (raw) => {
+                alive = true;
+                let frame;
+                try {
+                    frame = JSON.parse(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                this.queue = this.queue
+                    .then(async () => {
+                    if (conn.failed)
+                        return;
+                    if (frame.type === 'signal' && frame.signal)
+                        await this.deliver(frame.signal, frame.replay ? 'replay' : 'live');
+                    else if (frame.type === 'ready') {
+                        conn.live = true;
+                        this.emit({ type: 'live' });
+                    }
+                    // replay_truncated / replay_failed: the server closes with 4409 next; the reconnect resumes from lastId
+                })
+                    .catch((err) => {
+                    // keep the position and reconnect: the signal is offered again
+                    conn.failed = true;
+                    this.emit({ type: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+                    try {
+                        ws.terminate();
+                    }
+                    catch { /* already gone */ }
+                });
+            });
+            ws.on('error', (err) => this.emit({ type: 'error', error: err }));
+            ws.on('close', (code, reason) => {
+                if (conn.done)
+                    return;
+                this.emit({ type: 'disconnected', code, reason: reason?.toString() ?? '' });
+                if (code === 4402)
+                    this.fatal(new Error('stream closed (4402): the plan no longer includes the stream'));
+                finish();
+            });
+        });
+    }
+    /** true when the signal was new and handed to onSignal */
+    async deliver(s, source) {
+        // after stop(), nothing new reaches the handler (frames already queued are dropped, not delivered)
+        if (!this.running)
+            return false;
+        if (this.lastId !== null && BigInt(s.id) <= BigInt(this.lastId))
+            return false;
+        await this.opts.onSignal(s, { source });
+        // the in-memory position follows the saved one: a failed save offers the signal again
+        await this.store.save(s.id);
+        this.lastId = s.id;
+        return true;
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Response shapes of the LPSignal API (https://api.lpsignal.app/v1).
+ *
+ * Conventions:
+ * - APRs and ratios are fractions: 0.345 = 34.5%.
+ * - `ilApr` / `il7d` are the loss versus holding the two tokens, so they are ≤ 0, and `netApr = feeApr + ilApr`.
+ * - `fee` is in hundredths of a basis point: 500 = the 0.05% fee tier.
+ * - `rangeBp` is the range half-width in basis points of price: 500 = ±5%, 0 = full range.
+ * - Ids and 256-bit values are strings; timestamps are ISO 8601 strings in UTC.
+ */
+/** Chains scanned today. The API may add more, so any string is accepted. */
+export type Chain = 'ethereum' | 'bsc' | 'base' | 'arbitrum' | 'optimism' | 'polygon' | (string & {});
+export type PairClass = 'stable' | 'correlated' | 'volatile';
+export type WindowHours = 24 | 168 | 720;
+export type Tier = 'free' | 'basic' | 'pro';
+export type SignalKind = 'net_apr' | 'tvl_outflow' | 'depeg' | 'smart_lp';
+export interface Health {
+    ok: boolean;
+}
+export interface ChainStatus {
+    chain: Chain;
+    /** last block scanned */
+    block: string;
+    blockTs: string;
+    /** the first block this deployment scanned: history before it is not available */
+    firstBlockTs: string;
+    /** seconds between now and the last block scanned; chains more than 2h behind fire no signals */
+    lagSec: number;
+    activePools: number;
+}
+export interface BestRange {
+    windowHours: WindowHours;
+    rangeBp: number;
+    tickLower: number;
+    tickUpper: number;
+    /** fees measured from on-chain fee growth (only exact metrics fire signals) */
+    exact: boolean;
+    feeApr: number;
+    ilApr: number;
+    netApr: number;
+    inRangeRatio: number;
+    /** Slipstream: gauge emissions if staked instead (fees forgone, not backtested); 0 = not applicable */
+    stakedEmissionApr: number;
+    asOf: string;
+}
+export interface RankedPool {
+    chain: Chain;
+    /** 20-byte pool address, or the 32-byte pool id for Uniswap v4 */
+    address: string;
+    dex: string;
+    /** "SYMBOL0/SYMBOL1" */
+    pair: string;
+    fee: number;
+    pairClass: PairClass;
+    /** v4 pools: liquidity within ±2% of price, since v4 has no per-pool balances */
+    tvlUsd: number;
+    tvlAt: string | null;
+    best: BestRange;
+}
+export interface PoolsPage {
+    pools: RankedPool[];
+    limit: number;
+    offset: number;
+}
+export interface Pool {
+    id: string;
+    chain: Chain;
+    address: string;
+    status: string;
+    reason: string;
+    dex: string;
+    token0: string;
+    token1: string;
+    symbol0: string;
+    symbol1: string;
+    decimals0: number;
+    decimals1: number;
+    fee: number;
+    tickSpacing: number;
+    lpShare0: number;
+    lpShare1: number;
+    pairClass: PairClass;
+    gauge: string;
+    tvlUsd: number;
+    tvlAt: string | null;
+    paramsAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+export interface PoolMetric {
+    poolId: string;
+    windowHours: WindowHours;
+    rangeBp: number;
+    feeApr: number;
+    ilApr: number;
+    netApr: number;
+    inRangeRatio: number;
+    emissionApr: number;
+    tickLower: number;
+    tickUpper: number;
+    exact: boolean;
+    asOf: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PoolDetail {
+    pool: Pool;
+    metrics: PoolMetric[];
+}
+export interface PoolHour {
+    /** start of the hour */
+    hour: string;
+    swaps: number;
+    /** raw token units (not decimal-adjusted) */
+    volume0: number;
+    volume1: number;
+    /** fees earned per unit of in-range liquidity during the hour, raw token units */
+    fee0PerL: number;
+    fee1PerL: number;
+    openTick: number;
+    closeTick: number;
+    minTick: number;
+    maxTick: number;
+    /** uint128 liquidity, as a decimal string */
+    closeLiquidity: string;
+    /** fees come from on-chain fee growth rather than a Swap-log estimate */
+    feeExact: boolean;
+}
+export interface Backtest {
+    chain: Chain;
+    address: string;
+    rangeBp: number;
+    days: number;
+    asOf: string;
+    feeApr: number;
+    ilApr: number;
+    netApr: number;
+    inRangeRatio: number;
+    /** fees of hours that straddled a range edge: the true fee APR lies in [feeApr, feeApr + uncertainFeeApr] */
+    uncertainFeeApr: number;
+    startTick: number;
+    endTick: number;
+    tickLower: number;
+    tickUpper: number;
+    feesExact: boolean;
+    exact: boolean;
+}
+export interface SignalOutcome {
+    /** done = exact 7-day result; inexact = fees could not be attributed precisely (not a result) */
+    status: 'done' | 'inexact';
+    netApr: number | null;
+    feeApr: number | null;
+    ilApr: number | null;
+    evaluatedAt: string;
+}
+interface SignalBase {
+    /** increasing; resume streams and paging from it */
+    id: string;
+    firedAt: string;
+    chain: Chain;
+    dex: string;
+    pool: string;
+    pair: string;
+    fee: number;
+    pairClass: PairClass;
+    rangeBp: number;
+    entryTick: number;
+    tickLower: number;
+    tickUpper: number;
+    /** only opportunities are scored; null until 7 days have passed (and always null for other kinds) */
+    outcome: SignalOutcome | null;
+}
+/** An opportunity: the recommended position is `tickLower..tickUpper`. */
+export interface NetAprSignal extends SignalBase {
+    kind: 'net_apr';
+    tvlUsd: number;
+    net24h: number;
+    net7d: number;
+    /** null until the pool has 30 days of history */
+    net30d: number | null;
+    fee7d: number;
+    il7d: number;
+    inRange7d: number;
+    stakedEmissionApr?: number;
+}
+/** Liquidity fell by `drop` within `windowHours`, valued at current prices. */
+export interface TvlOutflowSignal extends SignalBase {
+    kind: 'tvl_outflow';
+    tvlBeforeUsd: number;
+    tvlNowUsd: number;
+    drop: number;
+    windowHours: number;
+}
+/** token0 trades `deviation` away from its 7-day median against token1. */
+export interface DepegSignal extends SignalBase {
+    kind: 'depeg';
+    deviation: number;
+    severe: boolean;
+    medianTick: number;
+    tick: number;
+}
+/** A top-ranked or followed wallet opened a position (Pro). */
+export interface SmartLpSignal extends SignalBase {
+    kind: 'smart_lp';
+    owner: string;
+    tokenId: string;
+    entryUsd: number;
+    top: boolean;
+    rank: number | null;
+    wallet30d: {
+        positions: number;
+        pnlUsd: number;
+        returnPct: number;
+    } | null;
+}
+export type Signal = NetAprSignal | TvlOutflowSignal | DepegSignal | SmartLpSignal;
+export interface SignalsPage {
+    signals: Signal[];
+    /** pass as `before` for the next (older) page; null on the last page */
+    next: string | null;
+}
+export interface LeaderboardWallet {
+    rank: number;
+    /** masked (0x1234…abcd) unless the caller is on Pro */
+    owner: string;
+    positions: number;
+    wins: number;
+    capitalUsd: number;
+    /** LP result minus simply holding the deposited tokens */
+    pnlUsd: number;
+    returnPct: number;
+    chains: Chain[];
+}
+export interface Leaderboard {
+    windowDays: 30 | 90;
+    /** false = top 10 with masked addresses (not Pro) */
+    full: boolean;
+    wallets: LeaderboardWallet[];
+}
+interface PositionPool {
+    chain: Chain;
+    pool: string;
+    pair: string;
+    dex: string;
+    fee: number;
+}
+export interface OpenPosition extends PositionPool {
+    tokenId: string;
+    tickLower: number;
+    tickUpper: number;
+    openedAt: string | null;
+    staked: boolean;
+    entryUsd: number | null;
+}
+export interface ClosedPosition extends PositionPool {
+    tokenId: string;
+    lifecycle: number;
+    tickLower: number;
+    tickUpper: number;
+    openedAt: string | null;
+    closedAt: string;
+    /** false = funded by several holders, staked, or first seen mid-life: not counted in rankings */
+    scoreable: boolean;
+    capitalUsd: number | null;
+    pnlUsd: number | null;
+}
+export interface WalletPositions {
+    owner: string;
+    open: OpenPosition[];
+    closed: ClosedPosition[];
+}
+export interface Me {
+    id: string;
+    tier: Tier;
+    paid: boolean;
+    telegramLinked: boolean;
+    webhookUrl: string | null;
+    /** the wallet the account signs in with on lpsignal.app (null for API-key-only accounts) */
+    walletAddress: string | null;
+    hasApiKey: boolean;
+}
+/** Track record of opportunity signals with a known 7-day outcome, over the last `days`. */
+export interface SignalStats {
+    days: number;
+    /** exact outcomes (the only ones in the numbers below) */
+    scored: number;
+    /** evaluated without exact fees: never counted as a result */
+    inexact: number;
+    positive: number;
+    medianRealizedNetApr: number | null;
+    medianSignalNetApr: number | null;
+    worst: {
+        id: string;
+        pair: string;
+        chain: Chain;
+        netApr: number;
+    } | null;
+    /** at-signal vs realized net APR of the most recent (up to 500) scored signals */
+    points: {
+        id: string;
+        signalNetApr: number;
+        realizedNetApr: number;
+    }[];
+}
+export interface WebhookRegistration {
+    url: string;
+    /** shown only here: store it to verify deliveries */
+    secret: string;
+}
+export interface TelegramLink {
+    code: string;
+    instruction: string;
+}
+export interface Follow {
+    owner: string;
+    since: string;
+}
+export interface BillingStatus {
+    tier: Tier;
+    manual: {
+        tier: string;
+        until: string | null;
+    };
+    stripe: {
+        tier: string | null;
+        until: string | null;
+        status: string | null;
+        invoiceUnpaidSince: string | null;
+        syncedAt: string | null;
+    };
+    onSale: {
+        basic: boolean;
+        pro: boolean;
+    };
+}
+/** The body of a webhook delivery. */
+export interface WebhookEvent {
+    type: 'signal';
+    /** unique per delivery: deliveries are at-least-once, so skip ids already handled */
+    deliveryId: string;
+    signal: Signal;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Response shapes of the LPSignal API (https://api.lpsignal.app/v1).
+ *
+ * Conventions:
+ * - APRs and ratios are fractions: 0.345 = 34.5%.
+ * - `ilApr` / `il7d` are the loss versus holding the two tokens, so they are ≤ 0, and `netApr = feeApr + ilApr`.
+ * - `fee` is in hundredths of a basis point: 500 = the 0.05% fee tier.
+ * - `rangeBp` is the range half-width in basis points of price: 500 = ±5%, 0 = full range.
+ * - Ids and 256-bit values are strings; timestamps are ISO 8601 strings in UTC.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}