lpsignal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LPSignal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# lpsignal (Node.js)
+
+Official Node.js SDK for [LPSignal](https://lpsignal.app): net-of-IL APR signals for concentrated-liquidity pools.
+ESM, typed, Node ≥ 20. One runtime dependency (`ws`).
+
+```bash
+npm install lpsignal
+```
+
+## REST
+
+```ts
+import { LPSignal, LPSignalError } from 'lpsignal';
+
+const lps = new LPSignal({ apiKey: process.env.LPSIGNAL_API_KEY }); // key optional for public endpoints
+
+const { pools } = await lps.pools({ chain: 'base', window: 168, minTvlUsd: 1e6 });
+const detail = await lps.pool('base', pools[0].address);          // every (window × range) metric
+const bt = await lps.backtest('base', pools[0].address, { rangePct: 5, days: 7 });
+
+try {
+  await lps.walletPositions('0x...');
+} catch (e) {
+  if (e instanceof LPSignalError && e.code === 'pro_required') { /* upgrade */ }
+}
+```
+
+| Method | Endpoint | Key |
+|---|---|---|
+| `health()` · `chains()` | `/v1/health` · `/v1/chains` | – |
+| `pools({ chain, class, window, minTvlUsd, limit, offset })` | `GET /v1/pools` | – |
+| `pool(chain, address)` · `poolHours(chain, address, { hours })` | `GET /v1/pools/:chain/:address[/hours]` | – |
+| `backtest(chain, address, { rangePct, days })` | `GET …/backtest` | – |
+| `signals({ kind, limit, before })` · `signal(id)` | `GET /v1/signals[/:id]` | optional |
+| `signalStats({ days })` | `GET /v1/signals/stats` — the public track record | – |
+| `iterateSignals({ kind })` | every page, newest first | optional |
+| `signalsAfter(id)` | everything newer than `id`, oldest first | optional |
+| `smartLps({ windowDays, chain, limit })` | `GET /v1/smart-lps` | optional |
+| `walletPositions(owner)` | `GET /v1/smart-lps/:owner/positions` | Pro |
+| `follows()` · `follow(owner)` · `unfollow(owner)` | `/v1/me/follows` | Pro |
+| `me()` · `setWebhook(url)` · `deleteWebhook()` · `telegramLink()` | `/v1/me…` | yes |
+| `createApiKey()` | `POST /v1/me/api-key` — replaces the key, returned once | yes |
+| `billing({ refresh })` · `checkout(tier)` · `billingPortal()` | `/v1/billing…` | yes |
+
+Errors are `LPSignalError` with `status`, `code` (the API's `error` field), `body` and `requestId`. A `429` on a
+GET, PUT or DELETE is retried after its `Retry-After` (`maxRetries`, default 2).
+
+## Stream
+
+```ts
+import { LPSignal, SignalStream, FileLastIdStore } from 'lpsignal';
+
+const stream = new SignalStream({
+  client: new LPSignal({ apiKey: process.env.LPSIGNAL_API_KEY }), // Basic or Pro
+  store: new FileLastIdStore('./lpsignal-state.json'),
+  onSignal: async (signal, { source }) => {
+    // called once per signal, in id order, never concurrently; source = 'rest' | 'replay' | 'live'
+  },
+  onEvent: (e) => { if (e.type === 'fatal') console.error(e.error.message); },
+});
+await stream.start();
+// …
+await stream.stop();
+```
+
+- **First start** with an empty store: begins after the newest signal that exists now (or after `since` if given).
+- **Every (re)connect**: first fetches everything after the saved id over REST, repeating until a pass finds
+  nothing new, then connects with `?since=<id>`; anything at or below the saved id is dropped. No gap however long
+  you were away, and no duplicates while the process runs.
+- **Your handler decides progress**: the id is saved only after `onSignal` resolves. If it throws, the connection
+  is dropped and the signal is offered again. A crash after the handler but before the save also offers it again
+  after the restart: delivery is **at-least-once**, so make the handler idempotent on `signal.id`.
+- **No repeats even across crashes**: keep the last id in the same database transaction as your side effects
+  (write it inside `onSignal`), and pass a `store` that reads and writes that same row; its `save()` must only move
+  forward (e.g. `UPDATE … SET last_id = GREATEST(last_id, $1)`), since the stream also saves the starting point.
+- `stop()` waits for the signal being handled; nothing new is handed over after it is called. Don't await `stop()`
+  from inside `onSignal` (it would wait for itself). After a `fatal` event, call `stop()` before `start()` again.
+- **Fatal** (the stream stops): invalid key (401), a plan without the stream (402), or the plan expiring (4402).
+  Everything else (network drops, server restarts, 429 too many connections) reconnects with backoff.
+
+## Webhooks
+
+```ts
+import express from 'express';
+import { verifyWebhook, WebhookVerificationError } from 'lpsignal';
+
+app.post('/lpsignal', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = verifyWebhook(req.body, req.headers, process.env.LPSIGNAL_WEBHOOK_SECRET!);
+    // deliveries are at-least-once: skip event.deliveryId if already handled
+    res.sendStatus(200);
+  } catch (e) {
+    if (e instanceof WebhookVerificationError) return res.status(400).send(e.reason);
+    throw e;
+  }
+});
+```
+
+Pass the raw body (a `Buffer` or string), never re-serialised JSON. Deliveries older than 5 minutes are rejected
+(`toleranceSec`); every retry is signed afresh.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,128 @@
+import type { Backtest, BillingStatus, Chain, ChainStatus, Follow, Health, Leaderboard, Me, PairClass, PoolDetail, PoolHour, PoolsPage, Signal, SignalKind, SignalsPage, SignalStats, TelegramLink, WalletPositions, WebhookRegistration, WindowHours } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.lpsignal.app";
+/** A non-2xx answer from the API. `code` is the API's stable `error` field (e.g. `rate_limited`, `pro_required`). */
+export declare class LPSignalError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    /** `x-request-id` of the failed request: include it when contacting support */
+    readonly requestId: string | null;
+    readonly code: string | null;
+    constructor(status: number, body: unknown, 
+    /** `x-request-id` of the failed request: include it when contacting support */
+    requestId?: string | null);
+}
+export interface LPSignalOptions {
+    /** `lps_...`. Optional: public endpoints work without one (opportunity signals then arrive 24h late). */
+    apiKey?: string;
+    baseUrl?: string;
+    /** per-request timeout, default 15 s */
+    timeoutMs?: number;
+    /** how many times a 429 on a GET/PUT/DELETE is retried after its Retry-After, default 2 (0 = never) */
+    maxRetries?: number;
+    /** inject a fetch implementation (tests, proxies) */
+    fetch?: typeof fetch;
+}
+type Query = Record<string, string | number | undefined>;
+export interface PoolsQuery {
+    chain?: Chain;
+    class?: PairClass;
+    /** default 168 (7 days) */
+    window?: WindowHours;
+    minTvlUsd?: number;
+    /** 1..100, default 50 */
+    limit?: number;
+    offset?: number;
+}
+export interface SignalsQuery {
+    kind?: SignalKind;
+    /** 1..100, default 50 */
+    limit?: number;
+    /** only signals with a smaller id (the `next` of the previous page) */
+    before?: string;
+}
+/** REST client for the LPSignal API. */
+export declare class LPSignal {
+    readonly apiKey: string | null;
+    readonly baseUrl: string;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(opts?: LPSignalOptions);
+    /** The stream URL derived from the base URL (https → wss). */
+    get streamUrl(): string;
+    request<T>(method: string, path: string, opts?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
+    health(): Promise<Health>;
+    /** Scan progress per chain. */
+    chains(): Promise<ChainStatus[]>;
+    /** Active pools ranked by their best range's net APR over `window` hours. */
+    pools(query?: PoolsQuery): Promise<PoolsPage>;
+    /** One pool with every (window, range) metric. `address` is the pool id for Uniswap v4. */
+    pool(chain: Chain, address: string): Promise<PoolDetail>;
+    /** Hourly aggregates, oldest first (at most 720 hours). */
+    poolHours(chain: Chain, address: string, opts?: {
+        hours?: number;
+    }): Promise<PoolHour[]>;
+    /** Backtest a symmetric range of ±`rangePct`% (0 = full range) over the last `days` (1..30, default 7). */
+    backtest(chain: Chain, address: string, opts: {
+        rangePct: number;
+        days?: number;
+    }): Promise<Backtest>;
+    /** One page of signals, newest first. Without a paid key, opportunities appear once they are 24h old. */
+    signals(query?: SignalsQuery): Promise<SignalsPage>;
+    /** The public track record over the last `days` (7..365, default 30). */
+    signalStats(opts?: {
+        days?: number;
+    }): Promise<SignalStats>;
+    signal(id: string): Promise<Signal>;
+    /** Every signal matching `query`, newest first, following the `next` cursor page by page. */
+    iterateSignals(query?: Omit<SignalsQuery, 'before'>): AsyncGenerator<Signal>;
+    /**
+     * Every signal visible to this key with an id greater than `afterId`, oldest first. This is how a consumer that was
+     * offline catches up (the stream itself only replays the last 24 hours).
+     */
+    signalsAfter(afterId: string): Promise<Signal[]>;
+    /** Wallets ranked by LP pnl versus holding. Without Pro: the top 10 with masked addresses. */
+    smartLps(query?: {
+        windowDays?: 30 | 90;
+        chain?: Chain;
+        limit?: number;
+    }): Promise<Leaderboard>;
+    /** A wallet's open and closed positions (Pro). */
+    walletPositions(owner: string, opts?: {
+        limit?: number;
+    }): Promise<WalletPositions>;
+    /** Wallets you follow (Pro). */
+    follows(): Promise<Follow[]>;
+    /** Follow a wallet: its new positions of $10k+ become smart_lp signals for you (Pro, up to 50). */
+    follow(owner: string): Promise<{
+        owner: string;
+        following: true;
+    }>;
+    unfollow(owner: string): Promise<void>;
+    me(): Promise<Me>;
+    /** Set or replace the webhook. The signing secret is returned only here. */
+    setWebhook(url: string): Promise<WebhookRegistration>;
+    deleteWebhook(): Promise<void>;
+    /** Create a new API key for this account and return it (shown only here). The key used for this call stops working. */
+    createApiKey(): Promise<{
+        apiKey: string;
+    }>;
+    /** A one-time code: send `/start <code>` to the LPSignal Telegram bot. */
+    telegramLink(): Promise<TelegramLink>;
+    /** Current plan. `refresh: true` re-reads Stripe first (use it right after a checkout). */
+    billing(opts?: {
+        refresh?: boolean;
+    }): Promise<BillingStatus>;
+    /** A Stripe Checkout URL for a monthly plan. */
+    checkout(tier: 'basic' | 'pro'): Promise<{
+        url: string;
+    }>;
+    /** A Stripe Customer Portal URL (change plan, cancel, invoices). */
+    billingPortal(): Promise<{
+        url: string;
+    }>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,195 @@
+export const DEFAULT_BASE_URL = 'https://api.lpsignal.app';
+/** A non-2xx answer from the API. `code` is the API's stable `error` field (e.g. `rate_limited`, `pro_required`). */
+export class LPSignalError extends Error {
+    status;
+    body;
+    requestId;
+    code;
+    constructor(status, body, 
+    /** `x-request-id` of the failed request: include it when contacting support */
+    requestId = null) {
+        const code = body && typeof body === 'object' && typeof body.error === 'string' ? body.error : null;
+        super(`LPSignal API ${status}${code ? ` ${code}` : ''}${requestId ? ` (request ${requestId})` : ''}: ${typeof body === 'string' ? body : JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+        this.requestId = requestId;
+        this.name = 'LPSignalError';
+        this.code = code;
+    }
+}
+const enc = encodeURIComponent;
+const IDEMPOTENT = new Set(['GET', 'PUT', 'DELETE']);
+const MAX_RETRY_WAIT_MS = 60_000;
+/** REST client for the LPSignal API. */
+export class LPSignal {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(opts = {}) {
+        if (opts.apiKey !== undefined && !opts.apiKey.startsWith('lps_'))
+            throw new Error('LPSignal: apiKey must start with "lps_"');
+        this.apiKey = opts.apiKey ?? null;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 15_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    /** The stream URL derived from the base URL (https → wss). */
+    get streamUrl() {
+        return `${this.baseUrl.replace(/^http/, 'ws')}/v1/stream`;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const headers = { accept: 'application/json' };
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        if (opts.body !== undefined)
+            headers['content-type'] = 'application/json';
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            const text = await res.text();
+            let parsed = text;
+            if (text) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch { /* keep the raw text */ }
+            }
+            if (res.ok)
+                return (text ? parsed : undefined);
+            if (res.status === 429 && IDEMPOTENT.has(method) && attempt < this.maxRetries) {
+                const after = Number(res.headers.get('retry-after') ?? parsed?.retryAfterSec);
+                const waitMs = Math.min(MAX_RETRY_WAIT_MS, Number.isFinite(after) && after > 0 ? after * 1000 : 1000);
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            throw new LPSignalError(res.status, parsed, res.headers.get('x-request-id'));
+        }
+    }
+    // ── status ───────────────────────────────────────────────────────────────
+    health() {
+        return this.request('GET', '/v1/health');
+    }
+    /** Scan progress per chain. */
+    async chains() {
+        return (await this.request('GET', '/v1/chains')).chains;
+    }
+    // ── pools ────────────────────────────────────────────────────────────────
+    /** Active pools ranked by their best range's net APR over `window` hours. */
+    pools(query = {}) {
+        return this.request('GET', '/v1/pools', { query: { ...query } });
+    }
+    /** One pool with every (window, range) metric. `address` is the pool id for Uniswap v4. */
+    pool(chain, address) {
+        return this.request('GET', `/v1/pools/${enc(chain)}/${enc(address)}`);
+    }
+    /** Hourly aggregates, oldest first (at most 720 hours). */
+    async poolHours(chain, address, opts = {}) {
+        return (await this.request('GET', `/v1/pools/${enc(chain)}/${enc(address)}/hours`, { query: opts })).hours;
+    }
+    /** Backtest a symmetric range of ±`rangePct`% (0 = full range) over the last `days` (1..30, default 7). */
+    backtest(chain, address, opts) {
+        return this.request('GET', `/v1/pools/${enc(chain)}/${enc(address)}/backtest`, { query: opts });
+    }
+    // ── signals ──────────────────────────────────────────────────────────────
+    /** One page of signals, newest first. Without a paid key, opportunities appear once they are 24h old. */
+    signals(query = {}) {
+        return this.request('GET', '/v1/signals', { query: { ...query } });
+    }
+    /** The public track record over the last `days` (7..365, default 30). */
+    signalStats(opts = {}) {
+        return this.request('GET', '/v1/signals/stats', { query: opts });
+    }
+    signal(id) {
+        return this.request('GET', `/v1/signals/${enc(id)}`);
+    }
+    /** Every signal matching `query`, newest first, following the `next` cursor page by page. */
+    async *iterateSignals(query = {}) {
+        let before;
+        for (;;) {
+            const page = await this.signals({ ...query, limit: query.limit ?? 100, ...(before ? { before } : {}) });
+            for (const s of page.signals)
+                yield s;
+            if (!page.next)
+                return;
+            before = page.next;
+        }
+    }
+    /**
+     * Every signal visible to this key with an id greater than `afterId`, oldest first. This is how a consumer that was
+     * offline catches up (the stream itself only replays the last 24 hours).
+     */
+    async signalsAfter(afterId) {
+        const after = BigInt(afterId);
+        const newer = [];
+        for await (const s of this.iterateSignals()) {
+            if (BigInt(s.id) <= after)
+                break;
+            newer.push(s);
+        }
+        return newer.reverse();
+    }
+    // ── smart LPs ────────────────────────────────────────────────────────────
+    /** Wallets ranked by LP pnl versus holding. Without Pro: the top 10 with masked addresses. */
+    smartLps(query = {}) {
+        return this.request('GET', '/v1/smart-lps', { query: { ...query } });
+    }
+    /** A wallet's open and closed positions (Pro). */
+    walletPositions(owner, opts = {}) {
+        return this.request('GET', `/v1/smart-lps/${enc(owner)}/positions`, { query: opts });
+    }
+    /** Wallets you follow (Pro). */
+    async follows() {
+        return (await this.request('GET', '/v1/me/follows')).follows;
+    }
+    /** Follow a wallet: its new positions of $10k+ become smart_lp signals for you (Pro, up to 50). */
+    follow(owner) {
+        return this.request('PUT', `/v1/me/follows/${enc(owner)}`);
+    }
+    async unfollow(owner) {
+        await this.request('DELETE', `/v1/me/follows/${enc(owner)}`);
+    }
+    // ── account ──────────────────────────────────────────────────────────────
+    me() {
+        return this.request('GET', '/v1/me');
+    }
+    /** Set or replace the webhook. The signing secret is returned only here. */
+    setWebhook(url) {
+        return this.request('PUT', '/v1/me/webhook', { body: { url } });
+    }
+    async deleteWebhook() {
+        await this.request('DELETE', '/v1/me/webhook');
+    }
+    /** Create a new API key for this account and return it (shown only here). The key used for this call stops working. */
+    createApiKey() {
+        return this.request('POST', '/v1/me/api-key');
+    }
+    /** A one-time code: send `/start <code>` to the LPSignal Telegram bot. */
+    telegramLink() {
+        return this.request('POST', '/v1/me/telegram-link');
+    }
+    // ── billing ──────────────────────────────────────────────────────────────
+    /** Current plan. `refresh: true` re-reads Stripe first (use it right after a checkout). */
+    billing(opts = {}) {
+        return this.request('GET', '/v1/billing', { query: opts.refresh ? { refresh: 1 } : {} });
+    }
+    /** A Stripe Checkout URL for a monthly plan. */
+    checkout(tier) {
+        return this.request('POST', '/v1/billing/checkout', { body: { tier } });
+    }
+    /** A Stripe Customer Portal URL (change plan, cancel, invoices). */
+    billingPortal() {
+        return this.request('POST', '/v1/billing/portal');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAE3D,qHAAqH;AACrH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAG3B;IACA;IAEA;IALF,IAAI,CAAgB;IAC7B,YACW,MAAc,EACd,IAAa;IACtB,+EAA+E;IACtE,YAA2B,IAAI;QAExC,MAAM,IAAI,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAQ,IAA4B,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,IAA0B,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACpJ,KAAK,CAAC,gBAAgB,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,aAAa,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QANxJ,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QAEb,cAAS,GAAT,SAAS,CAAsB;QAIxC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAmCD,MAAM,GAAG,GAAG,kBAAkB,CAAC;AAC/B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AACrD,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC,wCAAwC;AACxC,MAAM,OAAO,QAAQ;IACV,MAAM,CAAgB;IACtB,OAAO,CAAS;IACR,SAAS,CAAS;IAClB,UAAU,CAAS;IACnB,SAAS,CAAe;IAEzC,YAAY,OAAwB,EAAE;QACpC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7H,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IACvC,CAAC;IAED,8DAA8D;IAC9D,IAAI,SAAS;QACX,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,OAA0C,EAAE;QACzF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACzC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/G,MAAM,OAAO,GAA2B,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;QACvE,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;QACjE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC1E,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;gBACpC,MAAM;gBACN,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;gBACrE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;aAC5C,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,MAAM,GAAY,IAAI,CAAC;YAC3B,IAAI,IAAI,EAAE,CAAC;gBAAC,IAAI,CAAC;oBAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,uBAAuB,CAAC,CAAC;YAAC,CAAC;YAClF,IAAI,GAAG,CAAC,EAAE;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAM,CAAC;YACpD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC9E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAK,MAAsC,EAAE,aAAa,CAAC,CAAC;gBAC/G,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBACtG,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;gBAChD,SAAS;YACX,CAAC;YACD,MAAM,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC;IACD,+BAA+B;IAC/B,KAAK,CAAC,MAAM;QACV,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAA4B,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;IACrF,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,KAAK,CAAC,QAAoB,EAAE;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,2FAA2F;IAC3F,IAAI,CAAC,KAAY,EAAE,OAAe;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,2DAA2D;IAC3D,KAAK,CAAC,SAAS,CAAC,KAAY,EAAE,OAAe,EAAE,OAA2B,EAAE;QAC1E,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAwB,KAAK,EAAE,aAAa,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACpI,CAAC;IACD,2GAA2G;IAC3G,QAAQ,CAAC,KAAY,EAAE,OAAe,EAAE,IAAyC;QAC/E,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,4EAA4E;IAC5E,yGAAyG;IACzG,OAAO,CAAC,QAAsB,EAAE;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,yEAAyE;IACzE,WAAW,CAAC,OAA0B,EAAE;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,CAAC,EAAU;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,6FAA6F;IAC7F,KAAK,CAAC,CAAC,cAAc,CAAC,QAAsC,EAAE;QAC5D,IAAI,MAA0B,CAAC;QAC/B,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACxG,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;gBAAE,MAAM,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAAE,OAAO;YACvB,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;IACD;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC5C,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK;gBAAE,MAAM;YACjC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,8FAA8F;IAC9F,QAAQ,CAAC,QAAiE,EAAE;QAC1E,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,kDAAkD;IAClD,eAAe,CAAC,KAAa,EAAE,OAA2B,EAAE;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,gCAAgC;IAChC,KAAK,CAAC,OAAO;QACX,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAwB,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC;IACtF,CAAC;IACD,mGAAmG;IACnG,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,KAAa;QAC1B,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,kBAAkB,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,4EAA4E;IAC5E,EAAE;QACA,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IACD,4EAA4E;IAC5E,UAAU,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACjD,CAAC;IACD,uHAAuH;IACvH,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChD,CAAC;IACD,0EAA0E;IAC1E,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACtD,CAAC;IAED,4EAA4E;IAC5E,2FAA2F;IAC3F,OAAO,CAAC,OAA8B,EAAE;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,gDAAgD;IAChD,QAAQ,CAAC,IAAqB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,sBAAsB,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,oEAAoE;IACpE,aAAa;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { LPSignal, LPSignalError, DEFAULT_BASE_URL } from './client.js';
+export type { LPSignalOptions, PoolsQuery, SignalsQuery } from './client.js';
+export { SignalStream, MemoryLastIdStore, FileLastIdStore } from './stream.js';
+export type { LastIdStore, SignalMeta, SignalStreamOptions, StreamEvent, SocketFactory, SocketLike } from './stream.js';
+export { verifyWebhook, WebhookVerificationError } from './webhook.js';
+export type { HeadersLike, WebhookFailure } from './webhook.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { LPSignal, LPSignalError, DEFAULT_BASE_URL } from './client.js';
+export { SignalStream, MemoryLastIdStore, FileLastIdStore } from './stream.js';
+export { verifyWebhook, WebhookVerificationError } from './webhook.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/stream.d.ts

@@ -0,0 +1,146 @@
+import WebSocket, { type ClientOptions } from 'ws';
+import { type LPSignal } from './client.js';
+import type { Signal } from './types.js';
+/**
+ * Where the stream is: the id of the last signal handled. Persist it to resume after a restart.
+ *
+ * To make a crash unable to repeat a signal's side effects, keep the id in the same database transaction as those
+ * effects (write it inside onSignal) and give the stream a store over that same row. Its save() must only move
+ * forward (e.g. `SET last_id = GREATEST(last_id, $1)`): the stream also saves the starting point with it.
+ */
+export interface LastIdStore {
+    load(): Promise<string | null>;
+    save(lastId: string): Promise<void>;
+}
+export declare class MemoryLastIdStore implements LastIdStore {
+    private id;
+    load(): Promise<string | null>;
+    save(lastId: string): Promise<void>;
+}
+/** A small JSON file, replaced atomically (temp file + rename) so a crash never leaves half a file. */
+export declare class FileLastIdStore implements LastIdStore {
+    readonly path: string;
+    constructor(path: string);
+    load(): Promise<string | null>;
+    save(lastId: string): Promise<void>;
+}
+/** How a signal reached you: REST catch-up after downtime, the stream's own replay, or live. */
+export interface SignalMeta {
+    source: 'rest' | 'replay' | 'live';
+}
+export type StreamEvent = 
+/** no saved position: starting after the newest signal that exists now */
+{
+    type: 'anchored';
+    lastId: string;
+}
+/** missed signals were fetched over REST before connecting */
+ | {
+    type: 'caught_up';
+    delivered: number;
+} | {
+    type: 'connecting';
+    url: string;
+} | {
+    type: 'connected';
+}
+/** the stream's replay finished: everything from here on is live */
+ | {
+    type: 'live';
+} | {
+    type: 'disconnected';
+    code: number;
+    reason: string;
+} | {
+    type: 'error';
+    error: Error;
+}
+/** unrecoverable (bad key, plan without the stream, plan expired): the stream has stopped */
+ | {
+    type: 'fatal';
+    error: Error;
+};
+/** The subset of the `ws` WebSocket the stream uses; injectable for tests. */
+export interface SocketLike {
+    on(event: 'open', cb: () => void): unknown;
+    on(event: 'message', cb: (data: WebSocket.RawData) => void): unknown;
+    on(event: 'close', cb: (code: number, reason: Buffer) => void): unknown;
+    on(event: 'error', cb: (err: Error) => void): unknown;
+    on(event: 'pong', cb: () => void): unknown;
+    on(event: 'unexpected-response', cb: (req: unknown, res: {
+        statusCode?: number;
+    }) => void): unknown;
+    ping(): void;
+    close(code?: number): void;
+    terminate(): void;
+}
+export type SocketFactory = (url: string, headers: Record<string, string>) => SocketLike;
+export interface SignalStreamOptions {
+    /** a client with a paid API key */
+    client: LPSignal;
+    /**
+     * Called for each signal in ascending id order, never concurrently. The position is saved only after this returns:
+     * if it throws, the connection is dropped and the signal is offered again after reconnecting. A crash between this
+     * returning and the position being saved also offers it again after the restart, so delivery is at-least-once:
+     * make the handler idempotent on `signal.id`, or keep the position in your own database (see LastIdStore).
+     */
+    onSignal: (signal: Signal, meta: SignalMeta) => void | Promise<void>;
+    onEvent?: (event: StreamEvent) => void;
+    /** default: in memory (a restart starts from "now") */
+    store?: LastIdStore;
+    /** start after this signal id when the store is empty (default: after the newest signal at start) */
+    since?: string;
+    pingIntervalMs?: number;
+    /** give up on a connection that has not opened after this long, default 15 s */
+    openTimeoutMs?: number;
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+    socketFactory?: SocketFactory;
+    /** extra options for the `ws` client, e.g. `{ agent }` for a proxy */
+    wsOptions?: ClientOptions;
+}
+/**
+ * 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 declare class SignalStream {
+    private readonly opts;
+    private readonly store;
+    private readonly socketFactory;
+    private lastId;
+    private queue;
+    private running;
+    private socket;
+    private loopDone;
+    private wake;
+    private starting;
+    private stopping;
+    /** the first-run starting point, chosen once and kept until it is saved (a retry must not pick a newer one) */
+    private anchor;
+    constructor(options: SignalStreamOptions);
+    /** Id of the last signal handed to onSignal (null before the first connection). */
+    get position(): string | null;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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(): Promise<void>;
+    private emit;
+    private fatal;
+    private loop;
+    /** Establish a position (first run) or fetch everything after it over REST. */
+    private catchUp;
+    /** One connection's life. Resolves when it closes; true when it went live. */
+    private connectOnce;
+    /** true when the signal was new and handed to onSignal */
+    private deliver;
+}