hood-alerts 0.1.0

package/dist/tiers/index.d.cts

@@ -0,0 +1,231 @@
+import { b as AlertEventKind } from '../types-DFPpTMWo.cjs';
+import { b as Rule } from '../schema-NnIdKFl2.cjs';
+import { Address } from 'viem';
+import { HoodClient } from 'hoodchain';
+import { F as FetchLogRangeOptions } from '../logs-D7sYBvSy.cjs';
+import 'zod';
+
+/**
+ * Tiering, as an enforced policy layer rather than a marketing page.
+ *
+ * Every limit here exists because it maps to a real cost the service pays:
+ *
+ * - `maxSubscriptions` / `maxRulesPerSubscription` bound the per-event fan-out.
+ * - `maxRuleComplexity` bounds how much work one rule can ask for.
+ * - `allowOnChainLookupFilters` gates the filters that cost an RPC read per
+ *   candidate event (liquidity, deployer reputation). This is the expensive
+ *   one, so it is the clearest free/premium line.
+ * - `maxAlertsPerHour` bounds delivery throughput.
+ * - `deliveryDelayMs` is the latency difference. Free alerts are held briefly;
+ *   premium alerts go out as soon as the block is confirmed. It is enforced in
+ *   the outbox (the delivery row carries `not_before`), so it survives a
+ *   restart instead of being a `setTimeout` that a crash erases.
+ * - `allowedKinds` keeps the highest-volume stream (every bonding-curve trade)
+ *   on the paid tier, because it is a firehose, not an alert.
+ */
+/** The two tiers. */
+type Tier = 'free' | 'premium';
+/** What a tier is allowed to do. */
+interface TierPolicy {
+    tier: Tier;
+    /** Max delivery targets one subscriber may have. */
+    maxSubscriptions: number;
+    /** Max rules per subscription. */
+    maxRulesPerSubscription: number;
+    /** Max {@link ruleComplexity} score for a single rule. */
+    maxRuleComplexity: number;
+    /** Max entries in a rule's token or deployer watchlist. */
+    maxWatchlistTokens: number;
+    /** Max alerts delivered per subscriber per rolling hour. */
+    maxAlertsPerHour: number;
+    /** How long alerts are held before delivery, in ms. */
+    deliveryDelayMs: number;
+    /** May rules use liquidity and reputation filters (each costs an RPC read). */
+    allowOnChainLookupFilters: boolean;
+    /** Event kinds this tier may subscribe to. */
+    allowedKinds: readonly AlertEventKind[];
+}
+/** The shipped policy table. Override per deployment through the service config. */
+declare const TIER_POLICIES: Record<Tier, TierPolicy>;
+/** A policy decision. `allowed: false` always carries a user-facing reason. */
+interface PolicyDecision {
+    allowed: boolean;
+    /** Present when `allowed` is false. Written to be shown to the subscriber. */
+    reason: string | null;
+}
+/** May this subscriber add another subscription? */
+declare function canAddSubscription(policy: TierPolicy, currentCount: number): PolicyDecision;
+/** May this rule be added to a subscription that already has `currentRuleCount` rules? */
+declare function canAddRule(policy: TierPolicy, rule: Rule, currentRuleCount: number): PolicyDecision;
+/** Is this rule within the tier's limits, regardless of how many exist? */
+declare function isRuleAllowed(policy: TierPolicy, rule: Rule): PolicyDecision;
+/** Resolve the policy for a tier. */
+declare function policyFor(tier: Tier, overrides?: Partial<Record<Tier, Partial<TierPolicy>>>): TierPolicy;
+
+/**
+ * Entitlements: who is premium, and why.
+ *
+ * The service resolves a subscriber's tier through exactly one interface, so
+ * there is a single place to audit and a single place to swap the commercial
+ * model. Two implementations ship:
+ *
+ * 1. {@link createStaticEntitlementProvider} is the documented default. Premium
+ *    subscribers come from configuration (`PREMIUM_SUBSCRIBERS` in the
+ *    environment). It has no dependencies, works offline, and is what a
+ *    self-hoster running the bot for their own community wants.
+ * 2. {@link createUsdgEntitlementProvider} is a working on-chain rail. It reads
+ *    USDG `Transfer` logs to the operator's receiving address from a wallet
+ *    the subscriber has linked, and accrues subscription time from those real
+ *    payments. It needs no facilitator, no card processor and no third-party
+ *    service: USDG is the chain's own dollar and the ledger is the chain.
+ *
+ * Wallet linking is signature-verified (EIP-191 `personal_sign` over a
+ * server-issued nonce), so a subscriber cannot claim someone else's payments
+ * by pasting their address.
+ */
+/** A resolved entitlement. */
+interface Entitlement {
+    subscriberId: string;
+    tier: Tier;
+    /** When premium lapses, ms since epoch. `null` for free or for a permanent grant. */
+    expiresAtMs: number | null;
+    /** Which provider decided this, for support and for `/tier`. */
+    source: string;
+}
+/** The single entitlement chokepoint. */
+interface EntitlementProvider {
+    /** Resolve a subscriber's tier. Must never throw: fall back to free. */
+    get(subscriberId: string): Promise<Entitlement>;
+}
+/**
+ * Configuration-driven entitlements: the documented default.
+ *
+ * @example
+ * ```ts
+ * const entitlements = createStaticEntitlementProvider({
+ *   premiumSubscribers: ['telegram:12345', 'discord:987654321'],
+ * })
+ * ```
+ */
+declare function createStaticEntitlementProvider(options: {
+    premiumSubscribers?: readonly string[];
+    /** Treat everyone as premium. For a private self-hosted deployment. */
+    allPremium?: boolean;
+}): EntitlementProvider;
+/** Lookup of the wallet a subscriber has verifiably linked. */
+interface WalletLinkStore {
+    /** The linked, signature-verified wallet for a subscriber, or `null`. */
+    walletOf(subscriberId: string): Promise<Address | null>;
+}
+/** Options for {@link createUsdgEntitlementProvider}. */
+interface UsdgEntitlementOptions {
+    client: HoodClient;
+    /** The operator's receiving address. Payments to any other address are ignored. */
+    receiver: Address;
+    /** Price of one subscription period, in whole USDG. */
+    pricePerPeriodUsdg: number;
+    /** Length of a period in days. @defaultValue `30` */
+    periodDays?: number;
+    /** Where verified wallet links come from. */
+    links: WalletLinkStore;
+    /** First block to scan for payments. @defaultValue `0n` */
+    fromBlock?: bigint;
+    /** Cache lifetime per subscriber, in ms. @defaultValue `300_000` (5 minutes) */
+    ttlMs?: number;
+    /** Retry/bisect options for the payment scan. */
+    logOptions?: FetchLogRangeOptions;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/**
+ * Accrue an expiry from a payment history. Each payment buys
+ * `floor(amount / price)` periods, starting from whenever the current
+ * entitlement would have lapsed, so renewing early extends rather than
+ * overwrites.
+ *
+ * Exported because it is the part worth testing on its own: everything else in
+ * the provider is a log query.
+ */
+declare function accrueExpiry(payments: readonly {
+    atMs: number;
+    amountUsdg: number;
+}[], pricePerPeriodUsdg: number, periodDays: number): number | null;
+/**
+ * On-chain USDG entitlements.
+ *
+ * @example
+ * ```ts
+ * const entitlements = createUsdgEntitlementProvider({
+ *   client: hood,
+ *   receiver: '0xYourReceivingAddress',
+ *   pricePerPeriodUsdg: 25,
+ *   links: store,           // the service's SQLite store implements WalletLinkStore
+ * })
+ * const entitlement = await entitlements.get('telegram:12345')
+ * ```
+ */
+declare function createUsdgEntitlementProvider(options: UsdgEntitlementOptions): EntitlementProvider;
+/**
+ * Chain several providers: the first one that returns premium wins. Lets an
+ * operator grant comps by configuration while still selling on chain.
+ */
+declare function chainEntitlementProviders(...providers: readonly EntitlementProvider[]): EntitlementProvider;
+/** The message a subscriber signs to link a wallet. */
+declare function linkMessage(subscriberId: string, nonce: string): string;
+/**
+ * Verify a wallet link signature (EIP-191 `personal_sign`).
+ *
+ * The subscriber signs {@link linkMessage} with the wallet that pays, and the
+ * service checks the signature before storing the link. Without this step,
+ * anyone could paste a paying subscriber's address and inherit their
+ * entitlement.
+ *
+ * @returns the checksummed address on success, `null` on any failure (bad
+ * signature shape, wrong signer, malformed address).
+ *
+ * @example
+ * ```ts
+ * const nonce = crypto.randomUUID()
+ * // the user signs linkMessage('telegram:12345', nonce) in their wallet
+ * const address = await verifyWalletLink('telegram:12345', nonce, wallet, signature)
+ * if (address) await store.linkWallet('telegram:12345', address)
+ * ```
+ */
+declare function verifyWalletLink(subscriberId: string, nonce: string, address: string, signature: string): Promise<Address | null>;
+
+/**
+ * The entitlement chokepoint.
+ *
+ * Every tier question in the codebase goes through this object: the bot asks
+ * it before accepting a subscription or a rule, and the dispatcher asks it
+ * before queuing a delivery. Nothing else reads {@link TIER_POLICIES}
+ * directly. One place to audit, one place to change the commercial model, no
+ * chance of the bot and the dispatcher disagreeing about who is premium.
+ */
+interface EntitlementGate {
+    /** Resolve tier, policy and expiry for a subscriber. */
+    resolve(subscriberId: string): Promise<{
+        entitlement: Entitlement;
+        policy: TierPolicy;
+    }>;
+    /** May they add another subscription? */
+    checkAddSubscription(subscriberId: string, currentCount: number): Promise<PolicyDecision>;
+    /** May they add this rule to a subscription with `currentRuleCount` rules? */
+    checkAddRule(subscriberId: string, rule: Rule, currentRuleCount: number): Promise<PolicyDecision>;
+    /** Is this rule within their tier, ignoring counts (used when editing)? */
+    checkRule(subscriberId: string, rule: Rule): Promise<PolicyDecision>;
+    /** How long a delivery for this subscriber is held before sending, in ms. */
+    deliveryDelayMs(subscriberId: string): Promise<number>;
+    /** Have they exhausted their hourly delivery budget? */
+    checkThroughput(subscriberId: string, deliveredInLastHour: number): Promise<PolicyDecision>;
+}
+/** Options for {@link createEntitlementGate}. */
+interface EntitlementGateOptions {
+    provider: EntitlementProvider;
+    /** Per-deployment overrides of the shipped tier table. */
+    policyOverrides?: Partial<Record<Tier, Partial<TierPolicy>>>;
+}
+/** Build the gate. */
+declare function createEntitlementGate(options: EntitlementGateOptions): EntitlementGate;
+
+export { type Entitlement, type EntitlementGate, type EntitlementGateOptions, type EntitlementProvider, type PolicyDecision, TIER_POLICIES, type Tier, type TierPolicy, type UsdgEntitlementOptions, type WalletLinkStore, accrueExpiry, canAddRule, canAddSubscription, chainEntitlementProviders, createEntitlementGate, createStaticEntitlementProvider, createUsdgEntitlementProvider, isRuleAllowed, linkMessage, policyFor, verifyWalletLink };

package/dist/tiers/index.d.ts

@@ -0,0 +1,231 @@
+import { b as AlertEventKind } from '../types-DFPpTMWo.js';
+import { b as Rule } from '../schema-DuDMPqpq.js';
+import { Address } from 'viem';
+import { HoodClient } from 'hoodchain';
+import { F as FetchLogRangeOptions } from '../logs-D7sYBvSy.js';
+import 'zod';
+
+/**
+ * Tiering, as an enforced policy layer rather than a marketing page.
+ *
+ * Every limit here exists because it maps to a real cost the service pays:
+ *
+ * - `maxSubscriptions` / `maxRulesPerSubscription` bound the per-event fan-out.
+ * - `maxRuleComplexity` bounds how much work one rule can ask for.
+ * - `allowOnChainLookupFilters` gates the filters that cost an RPC read per
+ *   candidate event (liquidity, deployer reputation). This is the expensive
+ *   one, so it is the clearest free/premium line.
+ * - `maxAlertsPerHour` bounds delivery throughput.
+ * - `deliveryDelayMs` is the latency difference. Free alerts are held briefly;
+ *   premium alerts go out as soon as the block is confirmed. It is enforced in
+ *   the outbox (the delivery row carries `not_before`), so it survives a
+ *   restart instead of being a `setTimeout` that a crash erases.
+ * - `allowedKinds` keeps the highest-volume stream (every bonding-curve trade)
+ *   on the paid tier, because it is a firehose, not an alert.
+ */
+/** The two tiers. */
+type Tier = 'free' | 'premium';
+/** What a tier is allowed to do. */
+interface TierPolicy {
+    tier: Tier;
+    /** Max delivery targets one subscriber may have. */
+    maxSubscriptions: number;
+    /** Max rules per subscription. */
+    maxRulesPerSubscription: number;
+    /** Max {@link ruleComplexity} score for a single rule. */
+    maxRuleComplexity: number;
+    /** Max entries in a rule's token or deployer watchlist. */
+    maxWatchlistTokens: number;
+    /** Max alerts delivered per subscriber per rolling hour. */
+    maxAlertsPerHour: number;
+    /** How long alerts are held before delivery, in ms. */
+    deliveryDelayMs: number;
+    /** May rules use liquidity and reputation filters (each costs an RPC read). */
+    allowOnChainLookupFilters: boolean;
+    /** Event kinds this tier may subscribe to. */
+    allowedKinds: readonly AlertEventKind[];
+}
+/** The shipped policy table. Override per deployment through the service config. */
+declare const TIER_POLICIES: Record<Tier, TierPolicy>;
+/** A policy decision. `allowed: false` always carries a user-facing reason. */
+interface PolicyDecision {
+    allowed: boolean;
+    /** Present when `allowed` is false. Written to be shown to the subscriber. */
+    reason: string | null;
+}
+/** May this subscriber add another subscription? */
+declare function canAddSubscription(policy: TierPolicy, currentCount: number): PolicyDecision;
+/** May this rule be added to a subscription that already has `currentRuleCount` rules? */
+declare function canAddRule(policy: TierPolicy, rule: Rule, currentRuleCount: number): PolicyDecision;
+/** Is this rule within the tier's limits, regardless of how many exist? */
+declare function isRuleAllowed(policy: TierPolicy, rule: Rule): PolicyDecision;
+/** Resolve the policy for a tier. */
+declare function policyFor(tier: Tier, overrides?: Partial<Record<Tier, Partial<TierPolicy>>>): TierPolicy;
+
+/**
+ * Entitlements: who is premium, and why.
+ *
+ * The service resolves a subscriber's tier through exactly one interface, so
+ * there is a single place to audit and a single place to swap the commercial
+ * model. Two implementations ship:
+ *
+ * 1. {@link createStaticEntitlementProvider} is the documented default. Premium
+ *    subscribers come from configuration (`PREMIUM_SUBSCRIBERS` in the
+ *    environment). It has no dependencies, works offline, and is what a
+ *    self-hoster running the bot for their own community wants.
+ * 2. {@link createUsdgEntitlementProvider} is a working on-chain rail. It reads
+ *    USDG `Transfer` logs to the operator's receiving address from a wallet
+ *    the subscriber has linked, and accrues subscription time from those real
+ *    payments. It needs no facilitator, no card processor and no third-party
+ *    service: USDG is the chain's own dollar and the ledger is the chain.
+ *
+ * Wallet linking is signature-verified (EIP-191 `personal_sign` over a
+ * server-issued nonce), so a subscriber cannot claim someone else's payments
+ * by pasting their address.
+ */
+/** A resolved entitlement. */
+interface Entitlement {
+    subscriberId: string;
+    tier: Tier;
+    /** When premium lapses, ms since epoch. `null` for free or for a permanent grant. */
+    expiresAtMs: number | null;
+    /** Which provider decided this, for support and for `/tier`. */
+    source: string;
+}
+/** The single entitlement chokepoint. */
+interface EntitlementProvider {
+    /** Resolve a subscriber's tier. Must never throw: fall back to free. */
+    get(subscriberId: string): Promise<Entitlement>;
+}
+/**
+ * Configuration-driven entitlements: the documented default.
+ *
+ * @example
+ * ```ts
+ * const entitlements = createStaticEntitlementProvider({
+ *   premiumSubscribers: ['telegram:12345', 'discord:987654321'],
+ * })
+ * ```
+ */
+declare function createStaticEntitlementProvider(options: {
+    premiumSubscribers?: readonly string[];
+    /** Treat everyone as premium. For a private self-hosted deployment. */
+    allPremium?: boolean;
+}): EntitlementProvider;
+/** Lookup of the wallet a subscriber has verifiably linked. */
+interface WalletLinkStore {
+    /** The linked, signature-verified wallet for a subscriber, or `null`. */
+    walletOf(subscriberId: string): Promise<Address | null>;
+}
+/** Options for {@link createUsdgEntitlementProvider}. */
+interface UsdgEntitlementOptions {
+    client: HoodClient;
+    /** The operator's receiving address. Payments to any other address are ignored. */
+    receiver: Address;
+    /** Price of one subscription period, in whole USDG. */
+    pricePerPeriodUsdg: number;
+    /** Length of a period in days. @defaultValue `30` */
+    periodDays?: number;
+    /** Where verified wallet links come from. */
+    links: WalletLinkStore;
+    /** First block to scan for payments. @defaultValue `0n` */
+    fromBlock?: bigint;
+    /** Cache lifetime per subscriber, in ms. @defaultValue `300_000` (5 minutes) */
+    ttlMs?: number;
+    /** Retry/bisect options for the payment scan. */
+    logOptions?: FetchLogRangeOptions;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/**
+ * Accrue an expiry from a payment history. Each payment buys
+ * `floor(amount / price)` periods, starting from whenever the current
+ * entitlement would have lapsed, so renewing early extends rather than
+ * overwrites.
+ *
+ * Exported because it is the part worth testing on its own: everything else in
+ * the provider is a log query.
+ */
+declare function accrueExpiry(payments: readonly {
+    atMs: number;
+    amountUsdg: number;
+}[], pricePerPeriodUsdg: number, periodDays: number): number | null;
+/**
+ * On-chain USDG entitlements.
+ *
+ * @example
+ * ```ts
+ * const entitlements = createUsdgEntitlementProvider({
+ *   client: hood,
+ *   receiver: '0xYourReceivingAddress',
+ *   pricePerPeriodUsdg: 25,
+ *   links: store,           // the service's SQLite store implements WalletLinkStore
+ * })
+ * const entitlement = await entitlements.get('telegram:12345')
+ * ```
+ */
+declare function createUsdgEntitlementProvider(options: UsdgEntitlementOptions): EntitlementProvider;
+/**
+ * Chain several providers: the first one that returns premium wins. Lets an
+ * operator grant comps by configuration while still selling on chain.
+ */
+declare function chainEntitlementProviders(...providers: readonly EntitlementProvider[]): EntitlementProvider;
+/** The message a subscriber signs to link a wallet. */
+declare function linkMessage(subscriberId: string, nonce: string): string;
+/**
+ * Verify a wallet link signature (EIP-191 `personal_sign`).
+ *
+ * The subscriber signs {@link linkMessage} with the wallet that pays, and the
+ * service checks the signature before storing the link. Without this step,
+ * anyone could paste a paying subscriber's address and inherit their
+ * entitlement.
+ *
+ * @returns the checksummed address on success, `null` on any failure (bad
+ * signature shape, wrong signer, malformed address).
+ *
+ * @example
+ * ```ts
+ * const nonce = crypto.randomUUID()
+ * // the user signs linkMessage('telegram:12345', nonce) in their wallet
+ * const address = await verifyWalletLink('telegram:12345', nonce, wallet, signature)
+ * if (address) await store.linkWallet('telegram:12345', address)
+ * ```
+ */
+declare function verifyWalletLink(subscriberId: string, nonce: string, address: string, signature: string): Promise<Address | null>;
+
+/**
+ * The entitlement chokepoint.
+ *
+ * Every tier question in the codebase goes through this object: the bot asks
+ * it before accepting a subscription or a rule, and the dispatcher asks it
+ * before queuing a delivery. Nothing else reads {@link TIER_POLICIES}
+ * directly. One place to audit, one place to change the commercial model, no
+ * chance of the bot and the dispatcher disagreeing about who is premium.
+ */
+interface EntitlementGate {
+    /** Resolve tier, policy and expiry for a subscriber. */
+    resolve(subscriberId: string): Promise<{
+        entitlement: Entitlement;
+        policy: TierPolicy;
+    }>;
+    /** May they add another subscription? */
+    checkAddSubscription(subscriberId: string, currentCount: number): Promise<PolicyDecision>;
+    /** May they add this rule to a subscription with `currentRuleCount` rules? */
+    checkAddRule(subscriberId: string, rule: Rule, currentRuleCount: number): Promise<PolicyDecision>;
+    /** Is this rule within their tier, ignoring counts (used when editing)? */
+    checkRule(subscriberId: string, rule: Rule): Promise<PolicyDecision>;
+    /** How long a delivery for this subscriber is held before sending, in ms. */
+    deliveryDelayMs(subscriberId: string): Promise<number>;
+    /** Have they exhausted their hourly delivery budget? */
+    checkThroughput(subscriberId: string, deliveredInLastHour: number): Promise<PolicyDecision>;
+}
+/** Options for {@link createEntitlementGate}. */
+interface EntitlementGateOptions {
+    provider: EntitlementProvider;
+    /** Per-deployment overrides of the shipped tier table. */
+    policyOverrides?: Partial<Record<Tier, Partial<TierPolicy>>>;
+}
+/** Build the gate. */
+declare function createEntitlementGate(options: EntitlementGateOptions): EntitlementGate;
+
+export { type Entitlement, type EntitlementGate, type EntitlementGateOptions, type EntitlementProvider, type PolicyDecision, TIER_POLICIES, type Tier, type TierPolicy, type UsdgEntitlementOptions, type WalletLinkStore, accrueExpiry, canAddRule, canAddSubscription, chainEntitlementProviders, createEntitlementGate, createStaticEntitlementProvider, createUsdgEntitlementProvider, isRuleAllowed, linkMessage, policyFor, verifyWalletLink };

package/dist/tiers/index.js

@@ -0,0 +1,34 @@
+import "../chunk-O2RY2SWN.js";
+import {
+  TIER_POLICIES,
+  canAddRule,
+  canAddSubscription,
+  createEntitlementGate,
+  isRuleAllowed,
+  policyFor
+} from "../chunk-RSTLW7XH.js";
+import {
+  accrueExpiry,
+  chainEntitlementProviders,
+  createStaticEntitlementProvider,
+  createUsdgEntitlementProvider,
+  linkMessage,
+  verifyWalletLink
+} from "../chunk-W2GUAWUR.js";
+import "../chunk-VC5MKEY2.js";
+import "../chunk-3LHCQA4Z.js";
+export {
+  TIER_POLICIES,
+  accrueExpiry,
+  canAddRule,
+  canAddSubscription,
+  chainEntitlementProviders,
+  createEntitlementGate,
+  createStaticEntitlementProvider,
+  createUsdgEntitlementProvider,
+  isRuleAllowed,
+  linkMessage,
+  policyFor,
+  verifyWalletLink
+};
+//# sourceMappingURL=index.js.map

package/dist/tiers/index.js.map

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

package/dist/types-C0ETog04.d.ts

@@ -0,0 +1,109 @@
+import { P as Platform } from './schema-DuDMPqpq.js';
+
+/** A Discord embed field. */
+interface DiscordEmbedField {
+    name: string;
+    value: string;
+    inline?: boolean;
+}
+/** The subset of the Discord embed object this package produces. */
+interface DiscordEmbed {
+    title: string;
+    url?: string;
+    description?: string;
+    /** Decimal RGB, per Discord's API. */
+    color: number;
+    fields: DiscordEmbedField[];
+    footer?: {
+        text: string;
+    };
+    /** ISO-8601 timestamp. Omitted when the block time was not read. */
+    timestamp?: string;
+}
+/**
+ * One alert, rendered for every platform up front.
+ *
+ * Rendering once and letting each notifier pick its representation keeps the
+ * escaping rules next to each other (where they can be compared and tested
+ * together) and means a fan-out to Telegram and Discord formats the event
+ * once, not twice.
+ */
+interface RenderedAlert {
+    /** Telegram body, escaped for {@link RenderedAlert.parseMode}. */
+    text: string;
+    parseMode: 'HTML' | 'MarkdownV2';
+    /** Discord embed representation of the same alert. */
+    embed: DiscordEmbed;
+    /** Unstyled one-line summary, for logs and for platforms added later. */
+    plain: string;
+}
+/** What happened when a notifier tried to deliver. */
+interface DeliveryResult {
+    ok: boolean;
+    /** HTTP status of the final attempt, or `null` if the request never completed. */
+    status: number | null;
+    /** How many requests were made, including the successful one. */
+    attempts: number;
+    /** Platform message id, when the API returned one. */
+    messageId: string | null;
+    /** Failure detail. `null` on success. */
+    error: string | null;
+    /**
+     * `true` when the failure is worth retrying later (5xx, network, exhausted
+     * rate limit). `false` for a permanent rejection such as a bad chat id, so
+     * the service can disable a dead subscription instead of retrying forever.
+     */
+    retryable: boolean;
+}
+/** The one interface every delivery adapter implements. */
+interface Notifier {
+    readonly platform: Platform;
+    /** Adapter flavour, for logs and metrics: `bot`, `webhook`. */
+    readonly kind: string;
+    /**
+     * Deliver a rendered alert to a platform-specific target: a Telegram chat
+     * id, a Discord channel id, or a Discord webhook URL.
+     */
+    send(target: string, alert: RenderedAlert): Promise<DeliveryResult>;
+}
+/** The `fetch` shape the adapters use, so tests can substitute a double. */
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<FetchLikeResponse>;
+/** The response shape the adapters read. */
+interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** Options common to every HTTP-backed notifier. */
+interface NotifierHttpOptions {
+    /** Injected `fetch`. Defaults to the global. */
+    fetch?: FetchLike;
+    /** Max attempts per delivery, including the first. @defaultValue `4` */
+    maxAttempts?: number;
+    /** Base backoff in ms for retryable failures, doubled per attempt. @defaultValue `500` */
+    backoffMs?: number;
+    /**
+     * Upper bound on how long a single delivery will wait for a rate limit, in
+     * ms. A `retry_after` beyond this gives up and reports a retryable failure
+     * rather than blocking the whole dispatch loop.
+     * @defaultValue `60_000`
+     */
+    maxWaitMs?: number;
+    /** Sleep injection point for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Request timeout in ms. @defaultValue `15_000` */
+    timeoutMs?: number;
+}
+/** A successful send result. */
+declare function delivered(status: number, attempts: number, messageId: string | null): DeliveryResult;
+/** A failed send result. */
+declare function failed(status: number | null, attempts: number, error: string, retryable: boolean): DeliveryResult;
+
+export { type DeliveryResult as D, type FetchLike as F, type Notifier as N, type RenderedAlert as R, type DiscordEmbed as a, type DiscordEmbedField as b, type FetchLikeResponse as c, type NotifierHttpOptions as d, delivered as e, failed as f };