hood-alerts 0.1.0

package/dist/service/main.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/service/main.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/service/main.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import {
+  createService,
+  loadConfig
+} from "../chunk-Z4DJPESQ.js";
+import "../chunk-CBNZ6AZT.js";
+import "../chunk-Y2M3USWZ.js";
+import "../chunk-6JQK5G3Z.js";
+import "../chunk-SOBZ2FPP.js";
+import "../chunk-32GS6XVE.js";
+import "../chunk-NBMINJ5E.js";
+import "../chunk-RSTLW7XH.js";
+import "../chunk-W2GUAWUR.js";
+import "../chunk-VC5MKEY2.js";
+import "../chunk-3LHCQA4Z.js";
+
+// src/service/main.ts
+var GRACE_MS = 15e3;
+async function main() {
+  const config = loadConfig();
+  const service = createService({ config });
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) {
+      service.logger.warn("second signal received, exiting now", { signal });
+      process.exit(1);
+    }
+    shuttingDown = true;
+    service.logger.info("shutdown signal received", { signal });
+    const timer = setTimeout(() => {
+      service.logger.error("graceful shutdown timed out, exiting", { graceMs: GRACE_MS });
+      process.exit(1);
+    }, GRACE_MS);
+    timer.unref();
+    service.stop().then(() => process.exit(0)).catch((error) => {
+      service.logger.error("shutdown failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      process.exit(1);
+    });
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("unhandledRejection", (reason) => {
+    service.logger.error("unhandled rejection", {
+      error: reason instanceof Error ? reason.message : String(reason)
+    });
+  });
+  process.on("uncaughtException", (error) => {
+    service.logger.error("uncaught exception, shutting down", { error });
+    shutdown("uncaughtException");
+  });
+  await service.start();
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(JSON.stringify({ level: "error", message: `hood-alerts failed to start: ${message}` }));
+  process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/dist/service/main.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/service/main.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { loadConfig } from './config.js'\nimport { createService } from './runner.js'\n\n/**\n * The service entry point.\n *\n * Shutdown is graceful and bounded: SIGINT/SIGTERM stop the loops, close the\n * HTTP server and close SQLite. A second signal, or a shutdown that overruns\n * the grace period, exits immediately, because a container that ignores\n * SIGTERM gets SIGKILLed anyway and losing the clean close is worse than\n * exiting a few seconds early.\n */\n\nconst GRACE_MS = 15_000\n\nasync function main(): Promise<void> {\n  const config = loadConfig()\n  const service = createService({ config })\n\n  let shuttingDown = false\n  const shutdown = (signal: string): void => {\n    if (shuttingDown) {\n      service.logger.warn('second signal received, exiting now', { signal })\n      process.exit(1)\n    }\n    shuttingDown = true\n    service.logger.info('shutdown signal received', { signal })\n    const timer = setTimeout(() => {\n      service.logger.error('graceful shutdown timed out, exiting', { graceMs: GRACE_MS })\n      process.exit(1)\n    }, GRACE_MS)\n    timer.unref()\n    service\n      .stop()\n      .then(() => process.exit(0))\n      .catch((error: unknown) => {\n        service.logger.error('shutdown failed', {\n          error: error instanceof Error ? error.message : String(error),\n        })\n        process.exit(1)\n      })\n  }\n\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n  process.on('unhandledRejection', (reason) => {\n    service.logger.error('unhandled rejection', {\n      error: reason instanceof Error ? reason.message : String(reason),\n    })\n  })\n  process.on('uncaughtException', (error: Error) => {\n    service.logger.error('uncaught exception, shutting down', { error })\n    shutdown('uncaughtException')\n  })\n\n  await service.start()\n}\n\nmain().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : String(error)\n  console.error(JSON.stringify({ level: 'error', message: `hood-alerts failed to start: ${message}` }))\n  process.exit(1)\n})\n"],"mappings":";;;;;;;;;;;;;;;;;AAcA,IAAM,WAAW;AAEjB,eAAe,OAAsB;AACnC,QAAM,SAAS,WAAW;AAC1B,QAAM,UAAU,cAAc,EAAE,OAAO,CAAC;AAExC,MAAI,eAAe;AACnB,QAAM,WAAW,CAAC,WAAyB;AACzC,QAAI,cAAc;AAChB,cAAQ,OAAO,KAAK,uCAAuC,EAAE,OAAO,CAAC;AACrE,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,mBAAe;AACf,YAAQ,OAAO,KAAK,4BAA4B,EAAE,OAAO,CAAC;AAC1D,UAAM,QAAQ,WAAW,MAAM;AAC7B,cAAQ,OAAO,MAAM,wCAAwC,EAAE,SAAS,SAAS,CAAC;AAClF,cAAQ,KAAK,CAAC;AAAA,IAChB,GAAG,QAAQ;AACX,UAAM,MAAM;AACZ,YACG,KAAK,EACL,KAAK,MAAM,QAAQ,KAAK,CAAC,CAAC,EAC1B,MAAM,CAAC,UAAmB;AACzB,cAAQ,OAAO,MAAM,mBAAmB;AAAA,QACtC,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,MAC9D,CAAC;AACD,cAAQ,KAAK,CAAC;AAAA,IAChB,CAAC;AAAA,EACL;AAEA,UAAQ,GAAG,UAAU,MAAM,SAAS,QAAQ,CAAC;AAC7C,UAAQ,GAAG,WAAW,MAAM,SAAS,SAAS,CAAC;AAC/C,UAAQ,GAAG,sBAAsB,CAAC,WAAW;AAC3C,YAAQ,OAAO,MAAM,uBAAuB;AAAA,MAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AAAA,IACjE,CAAC;AAAA,EACH,CAAC;AACD,UAAQ,GAAG,qBAAqB,CAAC,UAAiB;AAChD,YAAQ,OAAO,MAAM,qCAAqC,EAAE,MAAM,CAAC;AACnE,aAAS,mBAAmB;AAAA,EAC9B,CAAC;AAED,QAAM,QAAQ,MAAM;AACtB;AAEA,KAAK,EAAE,MAAM,CAAC,UAAmB;AAC/B,QAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,UAAQ,MAAM,KAAK,UAAU,EAAE,OAAO,SAAS,SAAS,gCAAgC,OAAO,GAAG,CAAC,CAAC;AACpG,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/dist/sources-CAaQR6-N.d.ts

@@ -0,0 +1,159 @@
+import { Address, Hash } from 'viem';
+import { HoodClient } from 'hoodchain';
+import { F as FetchLogRangeOptions } from './logs-D7sYBvSy.js';
+import { P as PriceOracle } from './pricing-BumgLpvB.js';
+import { a as PoolRegistry } from './registry-D3We8Lg6.js';
+import { A as AlertEvent, e as Launchpad } from './types-DFPpTMWo.js';
+
+/** ERC-20 display metadata, with `null` for anything the contract does not answer. */
+interface TokenMeta {
+    address: Address;
+    symbol: string | null;
+    name: string | null;
+    /** Decimals, defaulting to 18 when the call reverts (the launchpad standard). */
+    decimals: number;
+}
+/** Cached reader for ERC-20 display metadata. */
+interface TokenMetaReader {
+    get(token: Address): Promise<TokenMeta>;
+    /** Prime the cache without a network round trip (used by the service store). */
+    prime(meta: TokenMeta): void;
+}
+/**
+ * Build a token metadata reader.
+ *
+ * Metadata is immutable in practice for launchpad tokens, so entries are
+ * cached for the process lifetime. A token whose `symbol()`/`name()` revert
+ * (some minimal proxies omit them) resolves to `null` fields rather than
+ * throwing, because a missing symbol must never drop an alert.
+ */
+declare function createTokenMetaReader(client: HoodClient, maxEntries?: number): TokenMetaReader;
+
+/** Cached block-timestamp reader. */
+interface BlockTimeReader {
+    /**
+     * Timestamp of `blockNumber` in ms, or `null` when it could not be read
+     * within the caller's budget. Events carry `timestampMs: null` in that case
+     * rather than a fabricated "now".
+     */
+    get(blockNumber: bigint): Promise<number | null>;
+    /**
+     * Resolve timestamps for a set of blocks, bounded by `maxLookups`. Blocks
+     * past the budget resolve to `null`: a backfill of a million blocks must not
+     * turn into a million `eth_getBlockByNumber` calls.
+     */
+    getMany(blocks: readonly bigint[], maxLookups: number): Promise<Map<bigint, number | null>>;
+}
+/** Build a block-timestamp reader with a bounded LRU cache. */
+declare function createBlockTimeReader(client: HoodClient, maxEntries?: number): BlockTimeReader;
+
+/**
+ * The event sources: one per on-chain surface, each responsible for turning a
+ * confirmed block range into normalized {@link AlertEvent}s.
+ *
+ * Sources are deliberately *pull* based (`poll(from, to)`) rather than
+ * push/subscription based. The service owns the block cursor and persists it,
+ * so a source that is asked for the same range twice must produce identical
+ * events, and it does: every event id is derived from `txHash` and `logIndex`.
+ * That is what makes crash recovery safe.
+ */
+/** A pollable on-chain source of alert events. */
+interface EventSource {
+    /** Stable identifier, used as the persisted cursor key. Never change it. */
+    id: string;
+    /** Human label for logs and `/metrics`. */
+    label: string;
+    /** Earliest block this source can produce events from. */
+    startBlock: bigint;
+    /** Decode `[from, to]` inclusive into events. Must be deterministic. */
+    poll(from: bigint, to: bigint): Promise<AlertEvent[]>;
+}
+/** Wiring shared by every source. */
+interface SourceContext {
+    client: HoodClient;
+    oracle: PriceOracle;
+    tokens: TokenMetaReader;
+    registry: PoolRegistry;
+    /** Optional shared block-timestamp reader (one is created when omitted). */
+    blockTimes?: BlockTimeReader;
+    /** Max `eth_getBlockByNumber` calls per poll, for timestamps. @defaultValue `25` */
+    maxBlockTimeLookupsPerPoll?: number;
+    /** Retry/bisect options passed to {@link fetchLogRange}. */
+    logOptions?: FetchLogRangeOptions;
+    /**
+     * Tokens that must always be in the whale watcher's pool set (subscriber
+     * watchlists). Called once per whale poll.
+     */
+    pinnedTokens?: () => Promise<readonly Address[]>;
+    /**
+     * Max pools the whale watcher queries per poll, newest first.
+     * @defaultValue `400`
+     */
+    whalePoolLimit?: number;
+    /**
+     * Service-wide floor for whale trades in USD. Swaps below this never become
+     * events at all, which keeps the delivery pipeline from doing per-subscriber
+     * work on dust. Per-subscription `minUsd` rules are applied on top and can
+     * only be stricter.
+     * @defaultValue `1000`
+     */
+    whaleMinUsd?: number;
+    /** Pools per address-filtered `eth_getLogs` call. @defaultValue `200` */
+    whalePoolBatchSize?: number;
+}
+/** Deterministic event id: reprocessing a range regenerates the same value. */
+declare function eventId(kind: string, transactionHash: Hash, logIndex: number): string;
+/**
+ * Build every event source for a mainnet client.
+ *
+ * @throws when the client targets testnet: neither launchpad exists there, so
+ * silently returning an empty source list would look like "no launches".
+ *
+ * @example
+ * ```ts
+ * import { createHoodClient } from 'hoodchain'
+ * import {
+ *   createEventSources, createPriceOracle, createTokenMetaReader, createMemoryPoolRegistry,
+ * } from 'hood-alerts/events'
+ *
+ * const hood = createHoodClient()
+ * const sources = createEventSources({
+ *   client: hood,
+ *   oracle: createPriceOracle(hood),
+ *   tokens: createTokenMetaReader(hood),
+ *   registry: createMemoryPoolRegistry(),
+ * })
+ * const head = await hood.public.getBlockNumber()
+ * for (const source of sources) {
+ *   console.log(source.label, (await source.poll(head - 2_000n, head)).length)
+ * }
+ * ```
+ */
+declare function createEventSources(ctx: SourceContext): EventSource[];
+/** NOXA `TokenLaunched`: an instant listing with a live Uniswap v3 pool. */
+declare function createNoxaLaunchSource(ctx: SourceContext): EventSource;
+/** The Odyssey `TokenCreated`: a bonding curve opening. */
+declare function createOdysseyLaunchSource(ctx: SourceContext): EventSource;
+/** The Odyssey `Traded`: every bonding-curve buy and sell. */
+declare function createOdysseyCurveTradeSource(ctx: SourceContext): EventSource;
+/**
+ * The Odyssey `PoolMigrated`: the curve filled and liquidity moved to a locked
+ * Uniswap v3 pool. This is the only real graduation event on the chain. NOXA
+ * cannot emit one, by construction.
+ */
+declare function createOdysseyGraduationSource(ctx: SourceContext): EventSource;
+/**
+ * Uniswap v3 swaps on known memecoin pools, above the service-wide USD floor.
+ *
+ * The pool set comes from {@link PoolRegistry}: NOXA pools are known from
+ * launch, Odyssey pools from graduation. That is a deliberate design choice,
+ * not a shortcut. A topic-only `Swap` query across the whole chain overflows
+ * the RPC's 10,000-log result cap inside 2,000 blocks, so "watch every pool"
+ * is not something the public endpoint can serve. Watching the launchpad pool
+ * set is both cheaper and exactly the product: memecoin whale alerts.
+ */
+declare function createWhaleTradeSource(ctx: SourceContext): EventSource;
+/** Every launchpad an event source can attribute an event to. */
+declare const SUPPORTED_LAUNCHPADS: readonly Launchpad[];
+
+export { type BlockTimeReader as B, type EventSource as E, SUPPORTED_LAUNCHPADS as S, type TokenMeta as T, type SourceContext as a, type TokenMetaReader as b, createBlockTimeReader as c, createEventSources as d, createNoxaLaunchSource as e, createOdysseyCurveTradeSource as f, createOdysseyGraduationSource as g, createOdysseyLaunchSource as h, createTokenMetaReader as i, createWhaleTradeSource as j, eventId as k };

package/dist/sources-CpDOUlzx.d.cts

@@ -0,0 +1,159 @@
+import { Address, Hash } from 'viem';
+import { HoodClient } from 'hoodchain';
+import { F as FetchLogRangeOptions } from './logs-D7sYBvSy.cjs';
+import { P as PriceOracle } from './pricing-BumgLpvB.cjs';
+import { a as PoolRegistry } from './registry-DePA3IyS.cjs';
+import { A as AlertEvent, e as Launchpad } from './types-DFPpTMWo.cjs';
+
+/** ERC-20 display metadata, with `null` for anything the contract does not answer. */
+interface TokenMeta {
+    address: Address;
+    symbol: string | null;
+    name: string | null;
+    /** Decimals, defaulting to 18 when the call reverts (the launchpad standard). */
+    decimals: number;
+}
+/** Cached reader for ERC-20 display metadata. */
+interface TokenMetaReader {
+    get(token: Address): Promise<TokenMeta>;
+    /** Prime the cache without a network round trip (used by the service store). */
+    prime(meta: TokenMeta): void;
+}
+/**
+ * Build a token metadata reader.
+ *
+ * Metadata is immutable in practice for launchpad tokens, so entries are
+ * cached for the process lifetime. A token whose `symbol()`/`name()` revert
+ * (some minimal proxies omit them) resolves to `null` fields rather than
+ * throwing, because a missing symbol must never drop an alert.
+ */
+declare function createTokenMetaReader(client: HoodClient, maxEntries?: number): TokenMetaReader;
+
+/** Cached block-timestamp reader. */
+interface BlockTimeReader {
+    /**
+     * Timestamp of `blockNumber` in ms, or `null` when it could not be read
+     * within the caller's budget. Events carry `timestampMs: null` in that case
+     * rather than a fabricated "now".
+     */
+    get(blockNumber: bigint): Promise<number | null>;
+    /**
+     * Resolve timestamps for a set of blocks, bounded by `maxLookups`. Blocks
+     * past the budget resolve to `null`: a backfill of a million blocks must not
+     * turn into a million `eth_getBlockByNumber` calls.
+     */
+    getMany(blocks: readonly bigint[], maxLookups: number): Promise<Map<bigint, number | null>>;
+}
+/** Build a block-timestamp reader with a bounded LRU cache. */
+declare function createBlockTimeReader(client: HoodClient, maxEntries?: number): BlockTimeReader;
+
+/**
+ * The event sources: one per on-chain surface, each responsible for turning a
+ * confirmed block range into normalized {@link AlertEvent}s.
+ *
+ * Sources are deliberately *pull* based (`poll(from, to)`) rather than
+ * push/subscription based. The service owns the block cursor and persists it,
+ * so a source that is asked for the same range twice must produce identical
+ * events, and it does: every event id is derived from `txHash` and `logIndex`.
+ * That is what makes crash recovery safe.
+ */
+/** A pollable on-chain source of alert events. */
+interface EventSource {
+    /** Stable identifier, used as the persisted cursor key. Never change it. */
+    id: string;
+    /** Human label for logs and `/metrics`. */
+    label: string;
+    /** Earliest block this source can produce events from. */
+    startBlock: bigint;
+    /** Decode `[from, to]` inclusive into events. Must be deterministic. */
+    poll(from: bigint, to: bigint): Promise<AlertEvent[]>;
+}
+/** Wiring shared by every source. */
+interface SourceContext {
+    client: HoodClient;
+    oracle: PriceOracle;
+    tokens: TokenMetaReader;
+    registry: PoolRegistry;
+    /** Optional shared block-timestamp reader (one is created when omitted). */
+    blockTimes?: BlockTimeReader;
+    /** Max `eth_getBlockByNumber` calls per poll, for timestamps. @defaultValue `25` */
+    maxBlockTimeLookupsPerPoll?: number;
+    /** Retry/bisect options passed to {@link fetchLogRange}. */
+    logOptions?: FetchLogRangeOptions;
+    /**
+     * Tokens that must always be in the whale watcher's pool set (subscriber
+     * watchlists). Called once per whale poll.
+     */
+    pinnedTokens?: () => Promise<readonly Address[]>;
+    /**
+     * Max pools the whale watcher queries per poll, newest first.
+     * @defaultValue `400`
+     */
+    whalePoolLimit?: number;
+    /**
+     * Service-wide floor for whale trades in USD. Swaps below this never become
+     * events at all, which keeps the delivery pipeline from doing per-subscriber
+     * work on dust. Per-subscription `minUsd` rules are applied on top and can
+     * only be stricter.
+     * @defaultValue `1000`
+     */
+    whaleMinUsd?: number;
+    /** Pools per address-filtered `eth_getLogs` call. @defaultValue `200` */
+    whalePoolBatchSize?: number;
+}
+/** Deterministic event id: reprocessing a range regenerates the same value. */
+declare function eventId(kind: string, transactionHash: Hash, logIndex: number): string;
+/**
+ * Build every event source for a mainnet client.
+ *
+ * @throws when the client targets testnet: neither launchpad exists there, so
+ * silently returning an empty source list would look like "no launches".
+ *
+ * @example
+ * ```ts
+ * import { createHoodClient } from 'hoodchain'
+ * import {
+ *   createEventSources, createPriceOracle, createTokenMetaReader, createMemoryPoolRegistry,
+ * } from 'hood-alerts/events'
+ *
+ * const hood = createHoodClient()
+ * const sources = createEventSources({
+ *   client: hood,
+ *   oracle: createPriceOracle(hood),
+ *   tokens: createTokenMetaReader(hood),
+ *   registry: createMemoryPoolRegistry(),
+ * })
+ * const head = await hood.public.getBlockNumber()
+ * for (const source of sources) {
+ *   console.log(source.label, (await source.poll(head - 2_000n, head)).length)
+ * }
+ * ```
+ */
+declare function createEventSources(ctx: SourceContext): EventSource[];
+/** NOXA `TokenLaunched`: an instant listing with a live Uniswap v3 pool. */
+declare function createNoxaLaunchSource(ctx: SourceContext): EventSource;
+/** The Odyssey `TokenCreated`: a bonding curve opening. */
+declare function createOdysseyLaunchSource(ctx: SourceContext): EventSource;
+/** The Odyssey `Traded`: every bonding-curve buy and sell. */
+declare function createOdysseyCurveTradeSource(ctx: SourceContext): EventSource;
+/**
+ * The Odyssey `PoolMigrated`: the curve filled and liquidity moved to a locked
+ * Uniswap v3 pool. This is the only real graduation event on the chain. NOXA
+ * cannot emit one, by construction.
+ */
+declare function createOdysseyGraduationSource(ctx: SourceContext): EventSource;
+/**
+ * Uniswap v3 swaps on known memecoin pools, above the service-wide USD floor.
+ *
+ * The pool set comes from {@link PoolRegistry}: NOXA pools are known from
+ * launch, Odyssey pools from graduation. That is a deliberate design choice,
+ * not a shortcut. A topic-only `Swap` query across the whole chain overflows
+ * the RPC's 10,000-log result cap inside 2,000 blocks, so "watch every pool"
+ * is not something the public endpoint can serve. Watching the launchpad pool
+ * set is both cheaper and exactly the product: memecoin whale alerts.
+ */
+declare function createWhaleTradeSource(ctx: SourceContext): EventSource;
+/** Every launchpad an event source can attribute an event to. */
+declare const SUPPORTED_LAUNCHPADS: readonly Launchpad[];
+
+export { type BlockTimeReader as B, type EventSource as E, SUPPORTED_LAUNCHPADS as S, type TokenMeta as T, type SourceContext as a, type TokenMetaReader as b, createBlockTimeReader as c, createEventSources as d, createNoxaLaunchSource as e, createOdysseyCurveTradeSource as f, createOdysseyGraduationSource as g, createOdysseyLaunchSource as h, createTokenMetaReader as i, createWhaleTradeSource as j, eventId as k };

package/dist/telegram-CpodYJrP.d.cts

@@ -0,0 +1,64 @@
+import { d as NotifierHttpOptions, N as Notifier } from './types-CcoKpStA.cjs';
+
+/**
+ * Telegram Bot API adapter.
+ *
+ * Rate limiting is the part everyone gets wrong. Telegram does not use a
+ * header budget: it answers `429` with a JSON body
+ * `{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 7",
+ * "parameters":{"retry_after":7}}` and expects the caller to wait exactly that
+ * many *seconds* before retrying. This adapter honours `parameters.retry_after`
+ * (falling back to the `Retry-After` header, then to exponential backoff), caps
+ * the total wait at `maxWaitMs` so one throttled chat cannot stall the whole
+ * dispatch loop, and treats `400`/`403` as permanent so a deleted chat or a
+ * blocked bot stops being retried forever.
+ */
+/** A raw Telegram Bot API response. */
+interface TelegramResponse {
+    ok: boolean;
+    status: number;
+    /** `result` on success. */
+    result: unknown;
+    /** `description` on failure. */
+    description: string | null;
+    /** `parameters.retry_after` in seconds, when Telegram sent one. */
+    retryAfterSeconds: number | null;
+}
+/** Options for {@link createTelegramClient}. */
+interface TelegramClientOptions extends NotifierHttpOptions {
+    /** Bot token from @BotFather, `<id>:<secret>`. */
+    botToken: string;
+    /** API origin. Override for a local Bot API server. @defaultValue `https://api.telegram.org` */
+    apiBase?: string;
+}
+/** A thin, rate-limit-aware Telegram Bot API client. */
+interface TelegramClient {
+    /** Call any Bot API method. Retries 429 and 5xx, never retries 4xx. */
+    call(method: string, params: Record<string, unknown>): Promise<TelegramResponse>;
+    /** How many requests the last {@link TelegramClient.call} needed. */
+    readonly lastAttempts: number;
+}
+/** Build a Telegram Bot API client. */
+declare function createTelegramClient(options: TelegramClientOptions): TelegramClient;
+/** Options for {@link createTelegramNotifier}. */
+interface TelegramNotifierOptions extends TelegramClientOptions {
+    /** Suppress link previews. @defaultValue `true` (alerts carry several links). */
+    disableWebPagePreview?: boolean;
+    /** Deliver silently, without a notification sound. @defaultValue `false` */
+    disableNotification?: boolean;
+    /** Reuse an existing client instead of building one (the bot shares its client). */
+    client?: TelegramClient;
+}
+/**
+ * Build the Telegram delivery adapter.
+ *
+ * @example
+ * ```ts
+ * const telegram = createTelegramNotifier({ botToken: process.env.TELEGRAM_BOT_TOKEN! })
+ * const result = await telegram.send('-1001234567890', renderAlert(event))
+ * if (!result.ok) console.error(result.error, 'retryable:', result.retryable)
+ * ```
+ */
+declare function createTelegramNotifier(options: TelegramNotifierOptions): Notifier;
+
+export { type TelegramClient as T, type TelegramClientOptions as a, type TelegramNotifierOptions as b, type TelegramResponse as c, createTelegramClient as d, createTelegramNotifier as e };

package/dist/telegram-pvphmBwn.d.ts

@@ -0,0 +1,64 @@
+import { d as NotifierHttpOptions, N as Notifier } from './types-C0ETog04.js';
+
+/**
+ * Telegram Bot API adapter.
+ *
+ * Rate limiting is the part everyone gets wrong. Telegram does not use a
+ * header budget: it answers `429` with a JSON body
+ * `{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 7",
+ * "parameters":{"retry_after":7}}` and expects the caller to wait exactly that
+ * many *seconds* before retrying. This adapter honours `parameters.retry_after`
+ * (falling back to the `Retry-After` header, then to exponential backoff), caps
+ * the total wait at `maxWaitMs` so one throttled chat cannot stall the whole
+ * dispatch loop, and treats `400`/`403` as permanent so a deleted chat or a
+ * blocked bot stops being retried forever.
+ */
+/** A raw Telegram Bot API response. */
+interface TelegramResponse {
+    ok: boolean;
+    status: number;
+    /** `result` on success. */
+    result: unknown;
+    /** `description` on failure. */
+    description: string | null;
+    /** `parameters.retry_after` in seconds, when Telegram sent one. */
+    retryAfterSeconds: number | null;
+}
+/** Options for {@link createTelegramClient}. */
+interface TelegramClientOptions extends NotifierHttpOptions {
+    /** Bot token from @BotFather, `<id>:<secret>`. */
+    botToken: string;
+    /** API origin. Override for a local Bot API server. @defaultValue `https://api.telegram.org` */
+    apiBase?: string;
+}
+/** A thin, rate-limit-aware Telegram Bot API client. */
+interface TelegramClient {
+    /** Call any Bot API method. Retries 429 and 5xx, never retries 4xx. */
+    call(method: string, params: Record<string, unknown>): Promise<TelegramResponse>;
+    /** How many requests the last {@link TelegramClient.call} needed. */
+    readonly lastAttempts: number;
+}
+/** Build a Telegram Bot API client. */
+declare function createTelegramClient(options: TelegramClientOptions): TelegramClient;
+/** Options for {@link createTelegramNotifier}. */
+interface TelegramNotifierOptions extends TelegramClientOptions {
+    /** Suppress link previews. @defaultValue `true` (alerts carry several links). */
+    disableWebPagePreview?: boolean;
+    /** Deliver silently, without a notification sound. @defaultValue `false` */
+    disableNotification?: boolean;
+    /** Reuse an existing client instead of building one (the bot shares its client). */
+    client?: TelegramClient;
+}
+/**
+ * Build the Telegram delivery adapter.
+ *
+ * @example
+ * ```ts
+ * const telegram = createTelegramNotifier({ botToken: process.env.TELEGRAM_BOT_TOKEN! })
+ * const result = await telegram.send('-1001234567890', renderAlert(event))
+ * if (!result.ok) console.error(result.error, 'retryable:', result.retryable)
+ * ```
+ */
+declare function createTelegramNotifier(options: TelegramNotifierOptions): Notifier;
+
+export { type TelegramClient as T, type TelegramClientOptions as a, type TelegramNotifierOptions as b, type TelegramResponse as c, createTelegramClient as d, createTelegramNotifier as e };