lovewebconnection 0.0.0-stage → 0.2.0

package/dist/alert-queue.d.ts

@@ -0,0 +1,72 @@
+import type { StoredAlert } from "./alert-store.ts";
+import type { WebhookResult } from "./webhook.ts";
+export interface AlertTarget {
+    url: string;
+    payload: Record<string, unknown>;
+}
+/** Durable backing for the queue; keeps undelivered alerts across restarts. */
+export interface AlertQueuePersistence {
+    load(): StoredAlert[];
+    save(alerts: StoredAlert[]): void;
+}
+export interface AlertQueueOptions {
+    deliver: (target: AlertTarget) => Promise<WebhookResult>;
+    /** Injected for tests; defaults to a cancellable timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /** First retry delay, doubled per attempt. Default 500 ms. */
+    baseDelayMs?: number;
+    /** Upper bound for a single backoff wait. Default 30 s. */
+    maxDelayMs?: number;
+    /**
+     * Attempts per alert before giving up. 0 (the default) retries until the
+     * receiver accepts, so a transient outage never drops an alert. A positive
+     * value is mainly useful in tests.
+     */
+    maxAttempts?: number;
+    /** When set, every queue change is written here and `restore()` replays it. */
+    store?: AlertQueuePersistence;
+    onRetry?: (target: AlertTarget, attempt: number, delayMs: number, message: string) => void;
+    onGiveUp?: (target: AlertTarget, attempts: number, message: string) => void;
+    /** A failed durable write is reported here; in-memory delivery continues. */
+    onPersistError?: (error: unknown) => void;
+}
+/**
+ * Serial alert delivery: one POST at a time, in enqueue order. A failed delivery
+ * stays at the head of the queue and is retried with exponential backoff, so a
+ * burst during an outage waits instead of firing concurrently and no alert is
+ * skipped. With a `store`, the pending queue is rewritten after every change:
+ * `stop()` clears memory but leaves the file intact, and `restore()` on the next
+ * run replays those alerts. Delivery is at-least-once — a crash between a
+ * successful POST and the store rewrite can resend one alert.
+ */
+export declare class AlertQueue {
+    private readonly items;
+    private readonly deliver;
+    private readonly customSleep;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly maxAttempts;
+    private readonly store;
+    private readonly onRetry;
+    private readonly onGiveUp;
+    private readonly onPersistError;
+    private loop;
+    private stopped;
+    private wake;
+    constructor(options: AlertQueueOptions);
+    get pending(): number;
+    /**
+     * Load alerts left by an earlier run and start delivering them. Attempts
+     * restart at zero so a restart tries immediately instead of waiting out the
+     * previous run's backoff.
+     */
+    restore(): number;
+    enqueue(target: AlertTarget): void;
+    /** Resolves once the current delivery loop has ended. */
+    flush(): Promise<void>;
+    stop(): void;
+    private start;
+    private run;
+    private persist;
+    private wait;
+}

package/dist/alert-queue.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Serial alert delivery: one POST at a time, in enqueue order. A failed delivery
+ * stays at the head of the queue and is retried with exponential backoff, so a
+ * burst during an outage waits instead of firing concurrently and no alert is
+ * skipped. With a `store`, the pending queue is rewritten after every change:
+ * `stop()` clears memory but leaves the file intact, and `restore()` on the next
+ * run replays those alerts. Delivery is at-least-once — a crash between a
+ * successful POST and the store rewrite can resend one alert.
+ */
+export class AlertQueue {
+    items = [];
+    deliver;
+    customSleep;
+    baseDelayMs;
+    maxDelayMs;
+    maxAttempts;
+    store;
+    onRetry;
+    onGiveUp;
+    onPersistError;
+    loop = null;
+    stopped = false;
+    wake = null;
+    constructor(options) {
+        this.deliver = options.deliver;
+        this.customSleep = options.sleep;
+        this.baseDelayMs = options.baseDelayMs ?? 500;
+        this.maxDelayMs = options.maxDelayMs ?? 30_000;
+        this.maxAttempts = options.maxAttempts ?? 0;
+        this.store = options.store;
+        this.onRetry = options.onRetry;
+        this.onGiveUp = options.onGiveUp;
+        this.onPersistError = options.onPersistError;
+    }
+    get pending() {
+        return this.items.length;
+    }
+    /**
+     * Load alerts left by an earlier run and start delivering them. Attempts
+     * restart at zero so a restart tries immediately instead of waiting out the
+     * previous run's backoff.
+     */
+    restore() {
+        if (!this.store)
+            return 0;
+        for (const alert of this.store.load()) {
+            this.items.push({
+                id: alert.id,
+                target: { url: alert.url, payload: alert.payload },
+                attempts: 0,
+                queuedAt: alert.queuedAt,
+            });
+        }
+        if (this.items.length > 0)
+            this.start();
+        return this.items.length;
+    }
+    enqueue(target) {
+        if (this.stopped)
+            return;
+        this.items.push({
+            id: randomUUID(),
+            target,
+            attempts: 0,
+            queuedAt: new Date().toISOString(),
+        });
+        this.persist();
+        this.start();
+    }
+    /** Resolves once the current delivery loop has ended. */
+    async flush() {
+        while (this.loop !== null)
+            await this.loop;
+    }
+    stop() {
+        this.stopped = true;
+        this.items.length = 0;
+        this.wake?.();
+    }
+    start() {
+        if (this.stopped || this.loop !== null)
+            return;
+        this.loop = this.run().finally(() => {
+            this.loop = null;
+        });
+    }
+    async run() {
+        while (!this.stopped && this.items.length > 0) {
+            const item = this.items[0];
+            if (item === undefined)
+                break;
+            item.attempts += 1;
+            this.persist();
+            let result;
+            try {
+                result = await this.deliver(item.target);
+            }
+            catch (error) {
+                result = {
+                    ok: false,
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            if (this.stopped)
+                break;
+            if (result.ok) {
+                this.items.shift();
+                this.persist();
+                continue;
+            }
+            const message = result.message ?? "unknown error";
+            if (this.maxAttempts > 0 && item.attempts >= this.maxAttempts) {
+                this.items.shift();
+                this.persist();
+                this.onGiveUp?.(item.target, item.attempts, message);
+                continue;
+            }
+            const delayMs = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** Math.max(0, item.attempts - 1));
+            this.onRetry?.(item.target, item.attempts, delayMs, message);
+            await this.wait(delayMs);
+        }
+    }
+    persist() {
+        if (!this.store)
+            return;
+        try {
+            this.store.save(this.items.map((item) => ({
+                id: item.id,
+                url: item.target.url,
+                payload: item.target.payload,
+                attempts: item.attempts,
+                queuedAt: item.queuedAt,
+            })));
+        }
+        catch (error) {
+            this.onPersistError?.(error);
+        }
+    }
+    wait(ms) {
+        if (this.customSleep)
+            return this.customSleep(ms);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.wake = null;
+                resolve();
+            }, ms);
+            this.wake = () => {
+                clearTimeout(timer);
+                this.wake = null;
+                resolve();
+            };
+        });
+    }
+}

package/dist/alert-store.d.ts

@@ -0,0 +1,29 @@
+/** One queued webhook alert as it appears in the durable queue file. */
+export interface StoredAlert {
+    id: string;
+    url: string;
+    payload: Record<string, unknown>;
+    /** Delivery attempts so far; informational, replay starts a fresh backoff. */
+    attempts: number;
+    /** ISO 8601 time the alert was first queued. */
+    queuedAt: string;
+}
+export declare const DEFAULT_ALERT_QUEUE_PATH = ".lwc-cache/webhook-queue.json";
+/**
+ * Flag path wins, then a path derived from the watch log, then the
+ * project-local default. A log-adjacent file keeps separate services apart
+ * without needing another flag.
+ */
+export declare function resolveAlertQueuePath(flagPath?: string | null, logPath?: string | null): string;
+/**
+ * JSON-file store for undelivered alerts. Writes go to a temporary file that is
+ * renamed over the real one, so a crash never leaves a half-written queue; an
+ * empty queue removes the file. Loading tolerates a missing, malformed or
+ * partially invalid file and keeps only usable entries.
+ */
+export declare class AlertStore {
+    readonly path: string;
+    constructor(path: string);
+    load(): StoredAlert[];
+    save(alerts: StoredAlert[]): void;
+}

package/dist/alert-store.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export const DEFAULT_ALERT_QUEUE_PATH = ".lwc-cache/webhook-queue.json";
+/**
+ * Flag path wins, then a path derived from the watch log, then the
+ * project-local default. A log-adjacent file keeps separate services apart
+ * without needing another flag.
+ */
+export function resolveAlertQueuePath(flagPath = null, logPath = null) {
+    const flag = flagPath?.trim();
+    if (flag)
+        return flag;
+    return logPath ? `${logPath}.alerts.json` : DEFAULT_ALERT_QUEUE_PATH;
+}
+function usableAlert(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const alert = value;
+    if (typeof alert.id !== "string" || alert.id.length === 0)
+        return null;
+    if (typeof alert.url !== "string" || !/^https?:\/\/\S+$/.test(alert.url))
+        return null;
+    const payload = alert.payload;
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const attempts = typeof alert.attempts === "number" && Number.isInteger(alert.attempts) && alert.attempts >= 0
+        ? alert.attempts
+        : 0;
+    return {
+        id: alert.id,
+        url: alert.url,
+        payload: payload,
+        attempts,
+        queuedAt: typeof alert.queuedAt === "string" ? alert.queuedAt : new Date(0).toISOString(),
+    };
+}
+/**
+ * JSON-file store for undelivered alerts. Writes go to a temporary file that is
+ * renamed over the real one, so a crash never leaves a half-written queue; an
+ * empty queue removes the file. Loading tolerates a missing, malformed or
+ * partially invalid file and keeps only usable entries.
+ */
+export class AlertStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            return [];
+        }
+        const alerts = parsed?.alerts;
+        if (!Array.isArray(alerts))
+            return [];
+        return alerts
+            .map(usableAlert)
+            .filter((alert) => alert !== null);
+    }
+    save(alerts) {
+        if (alerts.length === 0) {
+            rmSync(this.path, { force: true });
+            return;
+        }
+        mkdirSync(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ version: 1, alerts }, null, 2)}\n`);
+        renameSync(temporary, this.path);
+    }
+}

package/dist/balances.d.ts

@@ -0,0 +1,221 @@
+import { type Address, type PublicClient } from "viem";
+import type { ChainConfig } from "./chain.ts";
+import { type MetadataCache, type TokenMetadata } from "./metadata-cache.ts";
+export interface TokenBalance {
+    address: Address;
+    symbol: string;
+    /** Optional name from the token list or an inline `--token` label. */
+    label: string | null;
+    /** Null when the contract did not return a usable decimals value. */
+    decimals: number | null;
+    /** Null when balanceOf could not be read (not an ERC-20, or the call reverted). */
+    balance: bigint | null;
+    /** Age of the reused metadata entry; null when read fresh or unrecorded. */
+    cacheAgeMs: number | null;
+    /**
+     * Why this address does not look like a usable ERC-20, when it does not.
+     * Null for a token whose metadata all decoded cleanly.
+     */
+    issue: string | null;
+}
+export type ChunkStatus = "batched" | "recovered" | "partial" | "failed";
+export interface RecoverySummary {
+    /** Original chunks whose first aggregate3 request failed. */
+    failedChunks: number;
+    /** Retry requests sent for those chunks, two per multi-token chunk. */
+    retryRequests: number;
+    /** Chunks whose retries recovered every token. */
+    recoveredChunks: number;
+}
+export interface ChunkReport {
+    /** 1-based position among this owner's chunks. */
+    index: number;
+    total: number;
+    /** Tokens assigned to this chunk. */
+    tokens: number;
+    status: ChunkStatus;
+    /** Why the first batch attempt failed; null when it succeeded. */
+    error: string | null;
+    /** Tokens from this chunk that were re-read individually. */
+    individual: Address[];
+}
+export interface ChunkProgress extends ChunkReport {
+    owner: Address;
+}
+export interface CacheStats {
+    /** Unique tokens whose metadata was served from the cache. */
+    hits: number;
+    /** Unique tokens whose metadata had to be read. */
+    misses: number;
+}
+export interface BalancesReport {
+    owner: Address;
+    chainId: number;
+    chainName: string;
+    native: {
+        symbol: string;
+        decimals: number;
+        balance: bigint;
+    };
+    tokens: TokenBalance[];
+    blockNumber: bigint;
+    /** Why the Multicall3 batch could not be used, if it could not. */
+    batchWarning: string | null;
+    /** Tokens per Multicall3 request selected for this read. */
+    batchSize: number;
+    /** Number of Multicall3 chunks attempted. */
+    chunkCount: number;
+    /** Per-chunk outcomes, including retries and individual fallbacks. */
+    chunks: ChunkReport[];
+    /** First-attempt failures and their retry outcome. */
+    recovery: RecoverySummary;
+    /** Metadata cache hits and misses for this read. */
+    cache: CacheStats;
+}
+export declare class BalancesArgError extends Error {
+    constructor(message: string);
+}
+export interface BalanceArgs {
+    owner: Address;
+    tokens: Address[];
+    /** Lowercased token address → label from the token list file. */
+    labels: Map<string, string>;
+    /** Tokens per Multicall3 request. */
+    batchSize: number;
+    /** Fixed sub-call cap per Multicall3 request, independent of cache state. */
+    maxSubCalls: number | null;
+    /** Exit non-zero when any chunk needed a retry or individual fallback. */
+    failOnRetry: boolean;
+    /** Print one line per Multicall3 chunk, with its retry outcome, to stderr. */
+    verbose: boolean;
+    /** Refresh cached metadata older than this many milliseconds. */
+    maxCacheAgeMs: number | null;
+    /** Warn when cached metadata is older than this many milliseconds; never refreshes. */
+    staleAfterMs: number | null;
+    /** Non-fatal label conflicts found while merging token sources. */
+    warnings: string[];
+}
+/**
+ * Read a saved address list: a JSON array of addresses, or an object holding one
+ * of `keys` as that array (matching the tolerance of the ABI loader).
+ */
+export declare function loadAddressList(path: string, label: string, keys: string[]): Address[];
+export interface TokenListEntry {
+    address: Address;
+    label: string | null;
+}
+/** Parse an inline token spec: `0xAddress:Label` or `0xAddress=Label`. */
+export declare function parseTokenSpec(raw: string): TokenListEntry;
+/** Record the last label for a token, warning when a different one was present. */
+export declare function rememberTokenLabel(entry: TokenListEntry, labels: Map<string, string>, warnings: string[]): void;
+/**
+ * Merge ad-hoc and file labels. Inline `--token` labels win over the token
+ * file, and a differing file label is reported once rather than silently lost.
+ */
+export declare function mergeTokenLabels(inlineLabels: ReadonlyMap<string, string>, fileLabels: ReadonlyMap<string, string>, warnings: string[]): Map<string, string>;
+/**
+ * Saved token list: a JSON array of addresses, or `{ address, label }` objects,
+ * or an object with a `tokens` array of either.
+ */
+export declare function loadTokenList(path: string): TokenListEntry[];
+export declare function parseBalanceArgs(argv: string[]): BalanceArgs;
+/** Render a base-unit value without trailing zeros. */
+export declare function formatTokenAmount(value: bigint, decimals: number): string;
+/** Compact age for cached metadata: `45s`, `12m`, `5h`, `3d`. */
+/**
+ * Warn-only check for cached metadata older than `staleAfterMs`. Freshly read
+ * tokens and undated legacy entries carry no age, so they never warn.
+ */
+export declare function staleMetadataWarnings(tokens: readonly TokenBalance[], staleAfterMs: number | null): string[];
+export declare function formatCacheAge(ms: number): string;
+export declare function shortAddress(address: string): string;
+/** One stderr line per chunk for `--verbose`, matching `scan`'s progress text. */
+export declare function formatChunkProgress(chunk: ChunkProgress): string;
+/**
+ * Precompiles live at 0x…01–0x…0a. They have no code, so they can never be
+ * ERC-20s, and some (notably 0x05 modexp) read a 4-byte selector as an enormous
+ * operand length and burn every unit of gas available — which reverts the whole
+ * aggregate3 batch with "out of gas". They are answered locally instead.
+ */
+export declare function isPrecompileAddress(address: Address): boolean;
+/**
+ * One eth_call: native balance plus decimals/symbol/balanceOf/totalSupply for
+ * every token, through Multicall3 aggregate3. Returns null when the batch cannot
+ * be used at all, so the caller can fall back to individual reads.
+ */
+/** Default tokens per Multicall3 request: 12 uncached tokens is 49 sub-calls,
+ * comfortably within the 50M eth_call gas cap that a gas-burning address can
+ * otherwise exhaust. `--batch-size` lowers it for stricter RPCs. */
+export declare const TOKENS_PER_BATCH = 12;
+/** Cached tokens need only balanceOf and totalSupply, so 24 still fits 49. */
+export declare const CACHED_TOKENS_PER_BATCH = 24;
+export declare const MAX_BATCH_SIZE = 100;
+/** Upper bound for `--max-subcalls`: a fixed request budget, cache independent. */
+export declare const MAX_SUB_CALLS = 1000;
+export declare function readOwnerBatch(client: PublicClient, owner: Address, tokens: Address[], includeNative?: boolean, cache?: MetadataCache): Promise<{
+    ok: true;
+    native: bigint | null;
+    tokens: TokenBalance[];
+    metadata: Map<string, TokenMetadata>;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Read `decimals`/`symbol` once for every token missing from the cache. `scan`
+ * calls this before fanning out to owners so concurrent owners do not each
+ * re-read the same metadata.
+ */
+export declare function prefetchMetadata(client: PublicClient, tokens: Address[], cache: MetadataCache, batchSize?: number, maxSubCalls?: number): Promise<number>;
+/** Count unique ERC-20 metadata lookups the cache can answer. */
+export declare function countCacheStats(tokens: Address[], cache?: MetadataCache): CacheStats;
+export interface TokenCheck {
+    address: Address;
+    symbol: string | null;
+    decimals: number | null;
+    /** Why this address does not look like a usable ERC-20; null when it does. */
+    issue: string | null;
+}
+export interface TokenCheckOptions {
+    /** Tokens per Multicall3 request. */
+    batchSize?: number;
+    /** Fixed sub-call budget per request (3 per token), ignoring `batchSize`. */
+    maxSubCalls?: number;
+}
+/** Verification checks plus the request budget that produced them. */
+export interface TokenCheckReport {
+    checks: TokenCheck[];
+    /** Multicall3 verification requests sent; 0 when every address was local. */
+    chunkCount: number;
+    /** The sub-call cap used, or null when the default token batch size applied. */
+    maxSubCalls: number | null;
+}
+/**
+ * Read decimals, symbol and totalSupply for each address and classify it, so
+ * `tokens` can warn about entries that are not readable ERC-20s before saving
+ * them. Nothing here throws for a bad address: reverts, empty answers and batch
+ * failures all become an `issue`. The report also carries the number of
+ * Multicall3 verification requests and the cap that shaped them.
+ */
+export declare function checkTokenAddressesReport(client: PublicClient, tokens: Address[], options?: TokenCheckOptions): Promise<TokenCheckReport>;
+/** The classified checks only, for callers that do not need the request count. */
+export declare function checkTokenAddresses(client: PublicClient, tokens: Address[], options?: TokenCheckOptions): Promise<TokenCheck[]>;
+export interface BalancesOptions {
+    /** Reuse `decimals`/`symbol` seen on earlier runs instead of re-reading them. */
+    cache?: MetadataCache;
+    /** Ignore cached metadata for the requested tokens and re-read it. */
+    refreshCache?: boolean;
+    /** Refresh cached metadata older than this many milliseconds. */
+    maxCacheAgeMs?: number;
+    /** Lowercased address → label, shown next to the symbol in output. */
+    labels?: ReadonlyMap<string, string>;
+    /** Tokens per Multicall3 request; smaller values fit stricter gas caps. */
+    batchSize?: number;
+    /** Fixed sub-call cap per request; takes precedence over `batchSize`. */
+    maxSubCalls?: number;
+    /** Called once per chunk with its final status and fallback tokens. */
+    onChunkProgress?: (progress: ChunkProgress) => void;
+}
+export declare function readBalances(client: PublicClient, config: ChainConfig, owner: Address, tokens: Address[], options?: BalancesOptions): Promise<BalancesReport>;
+export declare function formatBalances(report: BalancesReport): string;
+export declare function toBalancesJson(report: BalancesReport): Record<string, unknown>;