hood-alerts 0.1.0

package/dist/logger-CYza_0eU.d.ts

@@ -0,0 +1,185 @@
+import { Address } from 'viem';
+import { a as PoolRegistry } from './registry-D3We8Lg6.js';
+import { a as RateLimitStore } from './ratelimit-CGLlXNIS.js';
+import { S as Subscription, P as Platform } from './schema-DuDMPqpq.js';
+import { WalletLinkStore } from './tiers/index.js';
+
+/**
+ * All durable service state, in one SQLite file, with no native dependency.
+ *
+ * The three invariants this schema exists to guarantee, in order of how badly
+ * they bite when they are missing:
+ *
+ * 1. **A restart never double-sends.** Every potential delivery has a
+ *    deterministic primary key (`eventId:subscriptionId:ruleId`), and
+ *    `enqueue` is an `INSERT` that reports a uniqueness violation as "already
+ *    queued". Re-processing a block range after a crash regenerates the exact
+ *    same keys, so the second pass inserts nothing.
+ * 2. **A restart never silently skips a range.** The block cursor advances
+ *    only after every event in a chunk has been enqueued and committed. A
+ *    crash mid-chunk leaves the cursor pointing at the start of that chunk, so
+ *    the range is simply re-read.
+ * 3. **A crash between enqueue and send does not lose the alert.** Enqueued
+ *    rows live in the outbox until they are delivered or dead-lettered. On
+ *    startup, rows left in `sending` (a crash mid-flight) are returned to
+ *    `pending` and retried.
+ *
+ * The one honest caveat: if the process dies after the platform accepted a
+ * message but before the row was marked `sent`, that alert is delivered twice.
+ * Neither the Telegram nor the Discord send API exposes a client-supplied
+ * idempotency key, so this window cannot be closed from here. Everything
+ * outside it is exactly once.
+ */
+/** Delivery lifecycle. */
+type OutboxStatus = 'pending' | 'sending' | 'sent' | 'failed' | 'dead';
+/** A queued delivery. */
+interface OutboxRow {
+    id: string;
+    subscriptionId: string;
+    subscriberId: string;
+    ruleId: string;
+    eventId: string;
+    eventJson: string;
+    platform: Platform;
+    target: string;
+    status: OutboxStatus;
+    /** Earliest delivery time, ms since epoch. Carries the free-tier delay. */
+    notBeforeMs: number;
+    attempts: number;
+    lastError: string | null;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** Aggregate counters for `/metrics`. */
+interface StoreMetrics {
+    subscriptions: number;
+    enabledSubscriptions: number;
+    outbox: Record<OutboxStatus, number>;
+    pools: number;
+    deliveriesLastHour: number;
+    cursors: {
+        sourceId: string;
+        nextBlock: bigint;
+    }[];
+}
+/** The service's durable state. */
+declare class AlertStore {
+    private readonly db;
+    private readonly clock;
+    constructor(path: string, clock?: () => number);
+    /** Deterministic outbox key. The whole dedupe guarantee rests on this. */
+    static deliveryKey(eventId: string, subscriptionId: string, ruleId: string): string;
+    /** The next unprocessed block for a source, or `null` when never persisted. */
+    getCursor(sourceId: string): bigint | null;
+    /** Persist the next unprocessed block. Call only after the range is enqueued. */
+    setCursor(sourceId: string, nextBlock: bigint): void;
+    /** Every persisted cursor, for `/metrics` and for operator inspection. */
+    listCursors(): {
+        sourceId: string;
+        nextBlock: bigint;
+    }[];
+    /** Insert or replace a subscription. */
+    saveSubscription(subscription: Subscription): void;
+    private hydrate;
+    /** One subscription by id. */
+    getSubscription(id: string): Subscription | null;
+    /** Every subscription owned by a subscriber. */
+    listSubscriptionsFor(subscriberId: string): Subscription[];
+    /** Every enabled subscription, for the dispatch fan-out. */
+    listEnabledSubscriptions(): Subscription[];
+    /** Remove a subscription. Returns `true` when a row was deleted. */
+    deleteSubscription(id: string): boolean;
+    /** Every token on any enabled subscription's watchlist, deduped. */
+    watchlistTokens(): Address[];
+    /**
+     * Queue a delivery.
+     *
+     * @returns `true` when this call created the row, `false` when it already
+     * existed (a replayed block range, a duplicate log). The boolean is the
+     * dedupe signal the dispatcher counts.
+     */
+    enqueue(row: Omit<OutboxRow, 'status' | 'attempts' | 'lastError' | 'createdAtMs' | 'updatedAtMs'>): boolean;
+    private static toOutboxRow;
+    /**
+     * Claim due deliveries, moving them to `sending` in one transaction so a
+     * second flush pass cannot pick up the same rows.
+     */
+    claimDue(nowMs: number, limit: number): OutboxRow[];
+    /** Mark a delivery sent. */
+    markSent(id: string): void;
+    /** Record a retryable failure and schedule the next attempt. */
+    markFailed(id: string, attempts: number, error: string, nextAttemptAtMs: number): void;
+    /** Give up on a delivery (permanent rejection, or attempts exhausted). */
+    markDead(id: string, attempts: number, error: string): void;
+    /**
+     * Return rows abandoned mid-flight by a crash to the queue.
+     *
+     * @returns how many rows were recovered.
+     */
+    recoverInFlight(): number;
+    /** Delete delivered rows older than `beforeMs`, keeping the file bounded. */
+    pruneOutbox(beforeMs: number): number;
+    /** Delete delivery history older than `beforeMs`. */
+    pruneDeliveries(beforeMs: number): number;
+    /** A {@link RateLimitStore} backed by the `deliveries` table. */
+    rateLimitStore(): RateLimitStore;
+    /** Record a delivery for both rate limiting and throughput accounting. */
+    recordDelivery(key: string, subscriberId: string, atMs: number): void;
+    /** How many alerts a subscriber received since `sinceMs`. */
+    countDeliveriesForSubscriber(subscriberId: string, sinceMs: number): number;
+    /** A {@link PoolRegistry} backed by the `pools` table. */
+    poolRegistry(): PoolRegistry;
+    private static toPoolEntry;
+    /** Store a signature-verified wallet link. */
+    linkWallet(subscriberId: string, address: Address): void;
+    /** A {@link WalletLinkStore} view of the links table. */
+    walletLinks(): WalletLinkStore;
+    /** Issue (or reissue) the nonce a subscriber must sign to link a wallet. */
+    issueLinkNonce(subscriberId: string, nonce: string): string;
+    /** The outstanding link nonce for a subscriber, or `null`. */
+    getLinkNonce(subscriberId: string): string | null;
+    /** Consume a link nonce so a signature cannot be replayed. */
+    clearLinkNonce(subscriberId: string): void;
+    /** Read a free-form service setting. */
+    getMeta(key: string): string | null;
+    /** Write a free-form service setting. */
+    setMeta(key: string, value: string): void;
+    /** Aggregate counters for `/metrics`. */
+    metrics(): StoreMetrics;
+    /** Close the database. Safe to call twice. */
+    close(): void;
+}
+
+/** Structured logging: one JSON object per line, machine-readable by default. */
+/** Log levels, ordered. */
+declare const LEVELS: readonly ["debug", "info", "warn", "error"];
+/** A log level. */
+type LogLevel = (typeof LEVELS)[number];
+/** Structured fields attached to a log line. */
+type LogFields = Record<string, unknown>;
+/** The logger the service uses everywhere. */
+interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    /** A logger that adds `fields` to every line, for per-component context. */
+    child(fields: LogFields): Logger;
+}
+/** Options for {@link createLogger}. */
+interface LoggerOptions {
+    /** Minimum level emitted. @defaultValue `'info'` */
+    level?: LogLevel;
+    /** Where lines go. @defaultValue `console.log` */
+    write?: (line: string) => void;
+    /** Fields added to every line. */
+    base?: LogFields;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** Build a structured logger. */
+declare function createLogger(options?: LoggerOptions): Logger;
+/** A logger that discards everything. For tests and for `--quiet`. */
+declare function createSilentLogger(): Logger;
+
+export { AlertStore as A, LEVELS as L, type OutboxRow as O, type StoreMetrics as S, type LogFields as a, type LogLevel as b, type Logger as c, type LoggerOptions as d, type OutboxStatus as e, createLogger as f, createSilentLogger as g };

package/dist/logs-D7sYBvSy.d.cts

@@ -0,0 +1,66 @@
+import { Address } from 'viem';
+
+/**
+ * Resilient log fetching for Robinhood Chain's public RPC.
+ *
+ * Two behaviours of the public endpoint drive this helper, both measured
+ * against `https://rpc.mainnet.chain.robinhood.com` while building this
+ * package:
+ *
+ * 1. **There is no block-range cap, but there is a 10,000-log result cap.**
+ *    A query spanning millions of blocks succeeds if it is selective enough
+ *    (the three Odyssey factories return every log they ever emitted in one
+ *    call); a query spanning 2,000 blocks fails with
+ *    `logs matched by query exceeds limit of 10000` if it is not (a topic-only
+ *    Uniswap v3 `Swap` query does). Fixed-size range chunking therefore
+ *    cannot guarantee success, so {@link fetchLogRange} bisects the range on
+ *    that specific error until each half fits.
+ * 2. **It rate limits bursts with `Too Many Requests`.** Those are retried
+ *    with exponential backoff rather than surfaced, because a retryable 429
+ *    must never advance a caller's block cursor.
+ */
+/** Options for {@link fetchLogRange}. */
+interface FetchLogRangeOptions {
+    /**
+     * Smallest range the bisector will produce. A single block that still
+     * overflows the result cap throws, because there is nothing left to split.
+     * @defaultValue `1n`
+     */
+    minSpan?: bigint;
+    /** Retries for rate-limit and transient transport errors. @defaultValue `5` */
+    retries?: number;
+    /** Base backoff in ms, doubled per attempt. @defaultValue `500` */
+    backoffMs?: number;
+    /** Sleep injection point for tests. @defaultValue a real timer */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** `true` when the RPC rejected the query for returning too many logs. */
+declare function isResultTooLarge(error: unknown): boolean;
+/** `true` when the error is a transient rate limit or timeout worth retrying. */
+declare function isRetryableRpcError(error: unknown): boolean;
+/**
+ * Fetch logs for `[from, to]` inclusive through `fetcher`, bisecting the range
+ * when the RPC reports too many results and retrying transient failures.
+ *
+ * @throws the underlying error when a single block still overflows the result
+ * cap, or when retries are exhausted. Callers must treat a throw as "range not
+ * processed" and leave their cursor untouched.
+ *
+ * @example
+ * ```ts
+ * const logs = await fetchLogRange(
+ *   (from, to) => hood.public.getLogs({ address: factory, event, fromBlock: from, toBlock: to }),
+ *   0n,
+ *   await hood.public.getBlockNumber(),
+ * )
+ * ```
+ */
+declare function fetchLogRange<T>(fetcher: (from: bigint, to: bigint) => Promise<readonly T[]>, from: bigint, to: bigint, options?: FetchLogRangeOptions): Promise<T[]>;
+/**
+ * Split a list of addresses into query-sized batches. The RPC accepts long
+ * address arrays, but batching keeps any single response under the result cap
+ * and keeps one failing batch from invalidating the whole set.
+ */
+declare function batchAddresses(addresses: readonly Address[], size?: number): Address[][];
+
+export { type FetchLogRangeOptions as F, isRetryableRpcError as a, batchAddresses as b, fetchLogRange as f, isResultTooLarge as i };

package/dist/logs-D7sYBvSy.d.ts

@@ -0,0 +1,66 @@
+import { Address } from 'viem';
+
+/**
+ * Resilient log fetching for Robinhood Chain's public RPC.
+ *
+ * Two behaviours of the public endpoint drive this helper, both measured
+ * against `https://rpc.mainnet.chain.robinhood.com` while building this
+ * package:
+ *
+ * 1. **There is no block-range cap, but there is a 10,000-log result cap.**
+ *    A query spanning millions of blocks succeeds if it is selective enough
+ *    (the three Odyssey factories return every log they ever emitted in one
+ *    call); a query spanning 2,000 blocks fails with
+ *    `logs matched by query exceeds limit of 10000` if it is not (a topic-only
+ *    Uniswap v3 `Swap` query does). Fixed-size range chunking therefore
+ *    cannot guarantee success, so {@link fetchLogRange} bisects the range on
+ *    that specific error until each half fits.
+ * 2. **It rate limits bursts with `Too Many Requests`.** Those are retried
+ *    with exponential backoff rather than surfaced, because a retryable 429
+ *    must never advance a caller's block cursor.
+ */
+/** Options for {@link fetchLogRange}. */
+interface FetchLogRangeOptions {
+    /**
+     * Smallest range the bisector will produce. A single block that still
+     * overflows the result cap throws, because there is nothing left to split.
+     * @defaultValue `1n`
+     */
+    minSpan?: bigint;
+    /** Retries for rate-limit and transient transport errors. @defaultValue `5` */
+    retries?: number;
+    /** Base backoff in ms, doubled per attempt. @defaultValue `500` */
+    backoffMs?: number;
+    /** Sleep injection point for tests. @defaultValue a real timer */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** `true` when the RPC rejected the query for returning too many logs. */
+declare function isResultTooLarge(error: unknown): boolean;
+/** `true` when the error is a transient rate limit or timeout worth retrying. */
+declare function isRetryableRpcError(error: unknown): boolean;
+/**
+ * Fetch logs for `[from, to]` inclusive through `fetcher`, bisecting the range
+ * when the RPC reports too many results and retrying transient failures.
+ *
+ * @throws the underlying error when a single block still overflows the result
+ * cap, or when retries are exhausted. Callers must treat a throw as "range not
+ * processed" and leave their cursor untouched.
+ *
+ * @example
+ * ```ts
+ * const logs = await fetchLogRange(
+ *   (from, to) => hood.public.getLogs({ address: factory, event, fromBlock: from, toBlock: to }),
+ *   0n,
+ *   await hood.public.getBlockNumber(),
+ * )
+ * ```
+ */
+declare function fetchLogRange<T>(fetcher: (from: bigint, to: bigint) => Promise<readonly T[]>, from: bigint, to: bigint, options?: FetchLogRangeOptions): Promise<T[]>;
+/**
+ * Split a list of addresses into query-sized batches. The RPC accepts long
+ * address arrays, but batching keeps any single response under the result cap
+ * and keeps one failing batch from invalidating the whole set.
+ */
+declare function batchAddresses(addresses: readonly Address[], size?: number): Address[][];
+
+export { type FetchLogRangeOptions as F, isRetryableRpcError as a, batchAddresses as b, fetchLogRange as f, isResultTooLarge as i };