hood-alerts 0.1.0

package/dist/service/index.d.cts

@@ -0,0 +1,262 @@
+import { b as LogLevel, A as AlertStore, c as Logger } from '../logger-3phvV_fl.cjs';
+export { L as LEVELS, a as LogFields, d as LoggerOptions, O as OutboxRow, e as OutboxStatus, S as StoreMetrics, f as createLogger, g as createSilentLogger } from '../logger-3phvV_fl.cjs';
+import { E as EventSource } from '../sources-CpDOUlzx.cjs';
+import { EvaluationContext } from '../rules/index.cjs';
+import { a as RateLimitStore } from '../ratelimit-BKVQG2oY.cjs';
+import { S as Subscription } from '../schema-NnIdKFl2.cjs';
+import { R as RenderOptions } from '../format-B7d40f65.cjs';
+import { N as Notifier } from '../types-CcoKpStA.cjs';
+import { EntitlementGate } from '../tiers/index.cjs';
+import { Server } from 'node:http';
+import { HoodClient } from 'hoodchain';
+import { A as AlertEvent } from '../types-DFPpTMWo.cjs';
+import 'viem';
+import '../registry-DePA3IyS.cjs';
+import '../logs-D7sYBvSy.cjs';
+import '../pricing-BumgLpvB.cjs';
+import 'zod';
+
+/** The validated service configuration. */
+interface ServiceConfig {
+    network: 'mainnet' | 'testnet';
+    rpcUrl: string | undefined;
+    dbPath: string;
+    port: number;
+    logLevel: LogLevel;
+    dryRun: boolean;
+    telegramBotToken: string | undefined;
+    discordBotToken: string | undefined;
+    discordApplicationId: string | undefined;
+    discordPublicKey: string | undefined;
+    discordInteractionsPath: string;
+    pollIntervalMs: number;
+    flushIntervalMs: number;
+    confirmations: bigint;
+    chunkSize: bigint;
+    initialLookbackBlocks: bigint;
+    whaleMinUsd: number;
+    whalePoolLimit: number;
+    flushBatchSize: number;
+    maxDeliveryAttempts: number;
+    retryBackoffMs: number;
+    outboxRetentionHours: number;
+    entitlements: 'static' | 'usdg' | 'both';
+    premiumSubscribers: string[];
+    allPremium: boolean;
+    usdgReceiver: `0x${string}` | undefined;
+    premiumPriceUsdg: number;
+    premiumPeriodDays: number;
+    paymentsFromBlock: bigint;
+    upgradeInstructions: string | undefined;
+}
+/**
+ * Load and validate configuration from the environment.
+ *
+ * @throws with every problem listed at once, so a misconfigured deployment
+ * needs one fix round rather than one per variable.
+ *
+ * @example
+ * ```ts
+ * const config = loadConfig()
+ * console.log(`watching ${config.network} with ${config.confirmations} confirmations`)
+ * ```
+ */
+declare function loadConfig(env?: NodeJS.ProcessEnv): ServiceConfig;
+
+/**
+ * The dispatcher: chain to inbox, in two independent halves.
+ *
+ * **`pollOnce`** reads confirmed block ranges, fans events out across
+ * subscriptions and rules, and writes matched deliveries into the outbox. It
+ * advances a source's cursor only after every event in the range has been
+ * enqueued and committed, which is the property that makes a crash safe:
+ * re-reading a range regenerates identical delivery ids and inserts nothing.
+ *
+ * **`flushOnce`** drains the outbox: claim due rows, render, send, mark the
+ * outcome, retry retryable failures with backoff, dead-letter permanent ones.
+ *
+ * Splitting them is what lets the free tier have a real delivery delay (the
+ * row carries `not_before`), lets a Telegram outage stall delivery without
+ * stalling ingestion, and keeps a slow platform from pushing the block cursor
+ * behind the chain.
+ */
+/** What one `pollOnce` did. */
+interface PollStats {
+    /** Blocks covered per source. */
+    ranges: {
+        sourceId: string;
+        from: bigint;
+        to: bigint;
+    }[];
+    eventsDecoded: number;
+    /** Deliveries newly written to the outbox. */
+    enqueued: number;
+    /** Matches that were already in the outbox (a replayed range). */
+    deduped: number;
+    /** Matches suppressed by a rule rate limit or a tier throughput cap. */
+    suppressed: number;
+    /** Sources that failed this pass. Their cursors did not advance. */
+    errors: {
+        sourceId: string;
+        error: string;
+    }[];
+}
+/** What one `flushOnce` did. */
+interface FlushStats {
+    claimed: number;
+    sent: number;
+    retried: number;
+    dead: number;
+}
+/** Options for {@link createDispatcher}. */
+interface DispatcherOptions {
+    store: AlertStore;
+    sources: readonly EventSource[];
+    gate: EntitlementGate;
+    rateLimits: RateLimitStore;
+    /** Resolve the adapter for a subscription. */
+    notifierFor: (subscription: Subscription) => Notifier | null;
+    /** Head block source. */
+    getBlockNumber: () => Promise<bigint>;
+    logger: Logger;
+    /** Lazy lookups for liquidity and reputation filters. */
+    evaluation?: EvaluationContext;
+    /** Telegram parse mode and footer options. */
+    render?: RenderOptions;
+    /** Confirmations before a block is processed. @defaultValue `2n` */
+    confirmations?: bigint;
+    /** Max blocks per poll per source. @defaultValue `2_000n` */
+    chunkSize?: bigint;
+    /**
+     * Where a source starts when it has no persisted cursor: this many blocks
+     * behind the head. A fresh deployment should not replay months of history
+     * into a subscriber's chat. @defaultValue `5_000n`
+     */
+    initialLookbackBlocks?: bigint;
+    /** Max outbox rows drained per flush. @defaultValue `50` */
+    flushBatchSize?: number;
+    /** Attempts before a delivery is dead-lettered. @defaultValue `6` */
+    maxDeliveryAttempts?: number;
+    /** Base retry backoff in ms, doubled per attempt. @defaultValue `30_000` */
+    retryBackoffMs?: number;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** The dispatcher. */
+interface Dispatcher {
+    /** Ingest one confirmed range per source. */
+    pollOnce(): Promise<PollStats>;
+    /** Deliver one batch of due outbox rows. */
+    flushOnce(): Promise<FlushStats>;
+    /** Return rows abandoned by a crash to the queue. Call once at startup. */
+    recover(): number;
+}
+/** Build the dispatcher. */
+declare function createDispatcher(options: DispatcherOptions): Dispatcher;
+
+/**
+ * The service's HTTP surface: `/health`, `/ready`, `/metrics`, and the Discord
+ * interactions endpoint when Discord is configured.
+ *
+ * Kept on `node:http` deliberately. The whole surface is four routes, and a
+ * framework would add a dependency, a middleware stack and a body parser that
+ * mangles the raw request body, which Discord's signature verification needs
+ * byte for byte.
+ */
+/** Liveness and readiness detail. */
+interface HealthState {
+    /** Head block the poller last saw. `null` before the first successful poll. */
+    headBlock: bigint | null;
+    /** When the poller last completed a pass, ms since epoch. */
+    lastPollAtMs: number | null;
+    /** Last poll error, if the most recent pass failed. */
+    lastError: string | null;
+    /** Which notifier platforms are configured. */
+    platforms: string[];
+    /** Version reported by `/health`. */
+    version: string;
+    /** Process start time, ms since epoch. */
+    startedAtMs: number;
+}
+/** Options for {@link createHttpServer}. */
+interface HttpServerOptions {
+    store: AlertStore;
+    logger: Logger;
+    /** Live health snapshot, read per request. */
+    health: () => HealthState;
+    /**
+     * Discord interactions handler, mounted at `interactionsPath`. Omitted when
+     * Discord is not configured, in which case the path 404s.
+     */
+    discord?: {
+        path: string;
+        handle(request: {
+            signature: string | null;
+            timestamp: string | null;
+            rawBody: string;
+        }): Promise<{
+            status: number;
+            body: unknown;
+        }>;
+    };
+    /**
+     * How stale the last successful poll may be before `/ready` reports 503, in
+     * ms. @defaultValue `120_000`
+     */
+    readinessStalenessMs?: number;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** Render Prometheus text-format metrics. */
+declare function renderMetrics(store: AlertStore, health: HealthState, nowMs: number): string;
+/** Build the HTTP server. Call `listen` yourself so startup order stays explicit. */
+declare function createHttpServer(options: HttpServerOptions): Server;
+
+/** Package version reported by `/health`. Kept in step with package.json. */
+declare const VERSION = "0.1.0";
+/** A wired, runnable service. */
+interface AlertService {
+    readonly config: ServiceConfig;
+    readonly store: AlertStore;
+    readonly dispatcher: Dispatcher;
+    readonly logger: Logger;
+    /** Current health snapshot. */
+    health(): HealthState;
+    /** Start the HTTP server, the poll loop, the flush loop and the bots. */
+    start(): Promise<void>;
+    /** Stop everything and close the database. Safe to call twice. */
+    stop(): Promise<void>;
+}
+/** Options for {@link createService}, all optional except the config. */
+interface CreateServiceOptions {
+    config: ServiceConfig;
+    /** Substitute the chain client (a test double, or a pre-configured client). */
+    client?: HoodClient;
+    /** Substitute the logger. */
+    logger?: Logger;
+    /** Substitute the store (`:memory:` in tests). */
+    store?: AlertStore;
+}
+/**
+ * Wire the whole service from a validated configuration.
+ *
+ * @example
+ * ```ts
+ * import { createService, loadConfig } from 'hood-alerts/service'
+ *
+ * const service = createService({ config: loadConfig() })
+ * await service.start()
+ * ```
+ */
+declare function createService(options: CreateServiceOptions): AlertService;
+
+/** Serialize any value containing bigints. */
+declare function encode(value: unknown): string;
+/** Restore a value serialized by {@link encode}. */
+declare function decode<T>(text: string): T;
+/** Serialize an alert event for the outbox. */
+declare function encodeEvent(event: AlertEvent): string;
+/** Restore an alert event from the outbox. */
+declare function decodeEvent(text: string): AlertEvent;
+
+export { type AlertService, AlertStore, type CreateServiceOptions, type Dispatcher, type DispatcherOptions, type FlushStats, type HealthState, type HttpServerOptions, LogLevel, Logger, type PollStats, type ServiceConfig, VERSION, createDispatcher, createHttpServer, createService, decode, decodeEvent, encode, encodeEvent, loadConfig, renderMetrics };

package/dist/service/index.d.ts

@@ -0,0 +1,262 @@
+import { b as LogLevel, A as AlertStore, c as Logger } from '../logger-CYza_0eU.js';
+export { L as LEVELS, a as LogFields, d as LoggerOptions, O as OutboxRow, e as OutboxStatus, S as StoreMetrics, f as createLogger, g as createSilentLogger } from '../logger-CYza_0eU.js';
+import { E as EventSource } from '../sources-CAaQR6-N.js';
+import { EvaluationContext } from '../rules/index.js';
+import { a as RateLimitStore } from '../ratelimit-CGLlXNIS.js';
+import { S as Subscription } from '../schema-DuDMPqpq.js';
+import { R as RenderOptions } from '../format-6RG4OcyE.js';
+import { N as Notifier } from '../types-C0ETog04.js';
+import { EntitlementGate } from '../tiers/index.js';
+import { Server } from 'node:http';
+import { HoodClient } from 'hoodchain';
+import { A as AlertEvent } from '../types-DFPpTMWo.js';
+import 'viem';
+import '../registry-D3We8Lg6.js';
+import '../logs-D7sYBvSy.js';
+import '../pricing-BumgLpvB.js';
+import 'zod';
+
+/** The validated service configuration. */
+interface ServiceConfig {
+    network: 'mainnet' | 'testnet';
+    rpcUrl: string | undefined;
+    dbPath: string;
+    port: number;
+    logLevel: LogLevel;
+    dryRun: boolean;
+    telegramBotToken: string | undefined;
+    discordBotToken: string | undefined;
+    discordApplicationId: string | undefined;
+    discordPublicKey: string | undefined;
+    discordInteractionsPath: string;
+    pollIntervalMs: number;
+    flushIntervalMs: number;
+    confirmations: bigint;
+    chunkSize: bigint;
+    initialLookbackBlocks: bigint;
+    whaleMinUsd: number;
+    whalePoolLimit: number;
+    flushBatchSize: number;
+    maxDeliveryAttempts: number;
+    retryBackoffMs: number;
+    outboxRetentionHours: number;
+    entitlements: 'static' | 'usdg' | 'both';
+    premiumSubscribers: string[];
+    allPremium: boolean;
+    usdgReceiver: `0x${string}` | undefined;
+    premiumPriceUsdg: number;
+    premiumPeriodDays: number;
+    paymentsFromBlock: bigint;
+    upgradeInstructions: string | undefined;
+}
+/**
+ * Load and validate configuration from the environment.
+ *
+ * @throws with every problem listed at once, so a misconfigured deployment
+ * needs one fix round rather than one per variable.
+ *
+ * @example
+ * ```ts
+ * const config = loadConfig()
+ * console.log(`watching ${config.network} with ${config.confirmations} confirmations`)
+ * ```
+ */
+declare function loadConfig(env?: NodeJS.ProcessEnv): ServiceConfig;
+
+/**
+ * The dispatcher: chain to inbox, in two independent halves.
+ *
+ * **`pollOnce`** reads confirmed block ranges, fans events out across
+ * subscriptions and rules, and writes matched deliveries into the outbox. It
+ * advances a source's cursor only after every event in the range has been
+ * enqueued and committed, which is the property that makes a crash safe:
+ * re-reading a range regenerates identical delivery ids and inserts nothing.
+ *
+ * **`flushOnce`** drains the outbox: claim due rows, render, send, mark the
+ * outcome, retry retryable failures with backoff, dead-letter permanent ones.
+ *
+ * Splitting them is what lets the free tier have a real delivery delay (the
+ * row carries `not_before`), lets a Telegram outage stall delivery without
+ * stalling ingestion, and keeps a slow platform from pushing the block cursor
+ * behind the chain.
+ */
+/** What one `pollOnce` did. */
+interface PollStats {
+    /** Blocks covered per source. */
+    ranges: {
+        sourceId: string;
+        from: bigint;
+        to: bigint;
+    }[];
+    eventsDecoded: number;
+    /** Deliveries newly written to the outbox. */
+    enqueued: number;
+    /** Matches that were already in the outbox (a replayed range). */
+    deduped: number;
+    /** Matches suppressed by a rule rate limit or a tier throughput cap. */
+    suppressed: number;
+    /** Sources that failed this pass. Their cursors did not advance. */
+    errors: {
+        sourceId: string;
+        error: string;
+    }[];
+}
+/** What one `flushOnce` did. */
+interface FlushStats {
+    claimed: number;
+    sent: number;
+    retried: number;
+    dead: number;
+}
+/** Options for {@link createDispatcher}. */
+interface DispatcherOptions {
+    store: AlertStore;
+    sources: readonly EventSource[];
+    gate: EntitlementGate;
+    rateLimits: RateLimitStore;
+    /** Resolve the adapter for a subscription. */
+    notifierFor: (subscription: Subscription) => Notifier | null;
+    /** Head block source. */
+    getBlockNumber: () => Promise<bigint>;
+    logger: Logger;
+    /** Lazy lookups for liquidity and reputation filters. */
+    evaluation?: EvaluationContext;
+    /** Telegram parse mode and footer options. */
+    render?: RenderOptions;
+    /** Confirmations before a block is processed. @defaultValue `2n` */
+    confirmations?: bigint;
+    /** Max blocks per poll per source. @defaultValue `2_000n` */
+    chunkSize?: bigint;
+    /**
+     * Where a source starts when it has no persisted cursor: this many blocks
+     * behind the head. A fresh deployment should not replay months of history
+     * into a subscriber's chat. @defaultValue `5_000n`
+     */
+    initialLookbackBlocks?: bigint;
+    /** Max outbox rows drained per flush. @defaultValue `50` */
+    flushBatchSize?: number;
+    /** Attempts before a delivery is dead-lettered. @defaultValue `6` */
+    maxDeliveryAttempts?: number;
+    /** Base retry backoff in ms, doubled per attempt. @defaultValue `30_000` */
+    retryBackoffMs?: number;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** The dispatcher. */
+interface Dispatcher {
+    /** Ingest one confirmed range per source. */
+    pollOnce(): Promise<PollStats>;
+    /** Deliver one batch of due outbox rows. */
+    flushOnce(): Promise<FlushStats>;
+    /** Return rows abandoned by a crash to the queue. Call once at startup. */
+    recover(): number;
+}
+/** Build the dispatcher. */
+declare function createDispatcher(options: DispatcherOptions): Dispatcher;
+
+/**
+ * The service's HTTP surface: `/health`, `/ready`, `/metrics`, and the Discord
+ * interactions endpoint when Discord is configured.
+ *
+ * Kept on `node:http` deliberately. The whole surface is four routes, and a
+ * framework would add a dependency, a middleware stack and a body parser that
+ * mangles the raw request body, which Discord's signature verification needs
+ * byte for byte.
+ */
+/** Liveness and readiness detail. */
+interface HealthState {
+    /** Head block the poller last saw. `null` before the first successful poll. */
+    headBlock: bigint | null;
+    /** When the poller last completed a pass, ms since epoch. */
+    lastPollAtMs: number | null;
+    /** Last poll error, if the most recent pass failed. */
+    lastError: string | null;
+    /** Which notifier platforms are configured. */
+    platforms: string[];
+    /** Version reported by `/health`. */
+    version: string;
+    /** Process start time, ms since epoch. */
+    startedAtMs: number;
+}
+/** Options for {@link createHttpServer}. */
+interface HttpServerOptions {
+    store: AlertStore;
+    logger: Logger;
+    /** Live health snapshot, read per request. */
+    health: () => HealthState;
+    /**
+     * Discord interactions handler, mounted at `interactionsPath`. Omitted when
+     * Discord is not configured, in which case the path 404s.
+     */
+    discord?: {
+        path: string;
+        handle(request: {
+            signature: string | null;
+            timestamp: string | null;
+            rawBody: string;
+        }): Promise<{
+            status: number;
+            body: unknown;
+        }>;
+    };
+    /**
+     * How stale the last successful poll may be before `/ready` reports 503, in
+     * ms. @defaultValue `120_000`
+     */
+    readinessStalenessMs?: number;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** Render Prometheus text-format metrics. */
+declare function renderMetrics(store: AlertStore, health: HealthState, nowMs: number): string;
+/** Build the HTTP server. Call `listen` yourself so startup order stays explicit. */
+declare function createHttpServer(options: HttpServerOptions): Server;
+
+/** Package version reported by `/health`. Kept in step with package.json. */
+declare const VERSION = "0.1.0";
+/** A wired, runnable service. */
+interface AlertService {
+    readonly config: ServiceConfig;
+    readonly store: AlertStore;
+    readonly dispatcher: Dispatcher;
+    readonly logger: Logger;
+    /** Current health snapshot. */
+    health(): HealthState;
+    /** Start the HTTP server, the poll loop, the flush loop and the bots. */
+    start(): Promise<void>;
+    /** Stop everything and close the database. Safe to call twice. */
+    stop(): Promise<void>;
+}
+/** Options for {@link createService}, all optional except the config. */
+interface CreateServiceOptions {
+    config: ServiceConfig;
+    /** Substitute the chain client (a test double, or a pre-configured client). */
+    client?: HoodClient;
+    /** Substitute the logger. */
+    logger?: Logger;
+    /** Substitute the store (`:memory:` in tests). */
+    store?: AlertStore;
+}
+/**
+ * Wire the whole service from a validated configuration.
+ *
+ * @example
+ * ```ts
+ * import { createService, loadConfig } from 'hood-alerts/service'
+ *
+ * const service = createService({ config: loadConfig() })
+ * await service.start()
+ * ```
+ */
+declare function createService(options: CreateServiceOptions): AlertService;
+
+/** Serialize any value containing bigints. */
+declare function encode(value: unknown): string;
+/** Restore a value serialized by {@link encode}. */
+declare function decode<T>(text: string): T;
+/** Serialize an alert event for the outbox. */
+declare function encodeEvent(event: AlertEvent): string;
+/** Restore an alert event from the outbox. */
+declare function decodeEvent(text: string): AlertEvent;
+
+export { type AlertService, AlertStore, type CreateServiceOptions, type Dispatcher, type DispatcherOptions, type FlushStats, type HealthState, type HttpServerOptions, LogLevel, Logger, type PollStats, type ServiceConfig, VERSION, createDispatcher, createHttpServer, createService, decode, decodeEvent, encode, encodeEvent, loadConfig, renderMetrics };

package/dist/service/index.js

@@ -0,0 +1,45 @@
+import "../chunk-PLMVKTQM.js";
+import {
+  AlertStore,
+  VERSION,
+  createDispatcher,
+  createHttpServer,
+  createService,
+  decode,
+  decodeEvent,
+  encode,
+  encodeEvent,
+  loadConfig,
+  renderMetrics
+} from "../chunk-Z4DJPESQ.js";
+import "../chunk-CBNZ6AZT.js";
+import "../chunk-Y2M3USWZ.js";
+import "../chunk-6JQK5G3Z.js";
+import "../chunk-SOBZ2FPP.js";
+import {
+  LEVELS,
+  createLogger,
+  createSilentLogger
+} from "../chunk-32GS6XVE.js";
+import "../chunk-NBMINJ5E.js";
+import "../chunk-RSTLW7XH.js";
+import "../chunk-W2GUAWUR.js";
+import "../chunk-VC5MKEY2.js";
+import "../chunk-3LHCQA4Z.js";
+export {
+  AlertStore,
+  LEVELS,
+  VERSION,
+  createDispatcher,
+  createHttpServer,
+  createLogger,
+  createService,
+  createSilentLogger,
+  decode,
+  decodeEvent,
+  encode,
+  encodeEvent,
+  loadConfig,
+  renderMetrics
+};
+//# sourceMappingURL=index.js.map

package/dist/service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}