@livo-build/runtime 0.2.1 → 0.2.2

package/dist/indexer.d.ts

@@ -0,0 +1,35 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface IndexerOptions {
+    /** Override the endpoint directly (takes precedence over env). */
+    url?: string;
+    /** env key holding the GraphQL endpoint. Default `INDEXER_<NAME>_URL`. */
+    urlSecret?: string;
+}
+export declare class GraphQLError extends Error {
+    readonly errors: unknown[];
+    constructor(message: string, errors: unknown[]);
+}
+/** Binding-name form of an indexer name: upper-snake (INDEXER_<THIS>_URL). */
+export declare function indexerEnvKey(name: string): string;
+export declare class Indexer {
+    readonly name: string;
+    readonly url: string | undefined;
+    constructor(env: MinimalEnv | undefined, name: string, options?: IndexerOptions);
+    /** True when the endpoint binding for this indexer was injected. */
+    get configured(): boolean;
+    /**
+     * Run a GraphQL query and return `data` (typed via the caller's generic).
+     * Throws on transport errors or GraphQL `errors`.
+     */
+    query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /** The subgraph's `_meta` — current head block + whether indexing has errored. */
+    meta(): Promise<{
+        block: number | null;
+        hasIndexingErrors: boolean;
+    }>;
+}
+/** Convenience: `await indexer(env, "hearth").query(gql, vars)`. */
+export declare function indexer(env: MinimalEnv | undefined, name: string, options?: IndexerOptions): Indexer;
+export {};

package/dist/indexer.js

@@ -0,0 +1,73 @@
+// Indexer — a typed GraphQL client for a project's Goldsky subgraph. A keeper /
+// bot / server reads `INDEXER_<NAME>_URL` (injected at deploy as the subgraph's
+// STABLE `live`-tag alias, NOT a version-pinned URL), so the worker never holds a
+// URL that breaks on the next sync_indexers/reindex. Just:
+//
+//   const { keepers } = await indexer(env, "hearth").query(
+//     `query($min:Int!){ keepers(where:{count_gte:$min}){ id count } }`, { min: 3 });
+//
+// Mirrors the Queue producer-binding pattern (queue.ts): a deployable gets the
+// binding injected by the platform; this wraps it so there's no fetch/URL/GraphQL
+// boilerplate to hand-roll. Pass an explicit `url` to point it anywhere (local dev).
+export class GraphQLError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = "GraphQLError";
+    }
+}
+/** Binding-name form of an indexer name: upper-snake (INDEXER_<THIS>_URL). */
+export function indexerEnvKey(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+export class Indexer {
+    name;
+    url;
+    constructor(env, name, options = {}) {
+        this.name = name;
+        const key = options.urlSecret ?? `INDEXER_${indexerEnvKey(name)}_URL`;
+        this.url = options.url ?? env?.[key];
+    }
+    /** True when the endpoint binding for this indexer was injected. */
+    get configured() {
+        return Boolean(this.url);
+    }
+    /**
+     * Run a GraphQL query and return `data` (typed via the caller's generic).
+     * Throws on transport errors or GraphQL `errors`.
+     */
+    async query(query, variables) {
+        if (!this.url) {
+            throw new Error(`indexer "${this.name}" not configured — no INDEXER_${indexerEnvKey(this.name)}_URL binding. ` +
+                `Deploy/sync the subgraph (create_indexer / sync_indexers) so the platform injects it, ` +
+                `or pass { url } for local dev.`);
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ query, variables: variables ?? {} }),
+        });
+        if (!res.ok) {
+            throw new Error(`indexer "${this.name}" query failed: HTTP ${res.status}`);
+        }
+        const json = (await res.json());
+        if (json.errors && json.errors.length) {
+            const first = json.errors[0];
+            throw new GraphQLError(`indexer "${this.name}" GraphQL error: ${first?.message ?? "unknown"}`, json.errors);
+        }
+        return json.data;
+    }
+    /** The subgraph's `_meta` — current head block + whether indexing has errored. */
+    async meta() {
+        const data = await this.query(`{ _meta { block { number } hasIndexingErrors } }`);
+        return {
+            block: data._meta?.block?.number ?? null,
+            hasIndexingErrors: Boolean(data._meta?.hasIndexingErrors),
+        };
+    }
+}
+/** Convenience: `await indexer(env, "hearth").query(gql, vars)`. */
+export function indexer(env, name, options) {
+    return new Indexer(env, name, options);
+}

package/dist/multicall.d.ts

@@ -0,0 +1,30 @@
+import { type AbiFunction } from "./abi.js";
+import { type Hex } from "./hex.js";
+/** Canonical Multicall3 (same address on mainnet, testnets, L2s, …). */
+export declare const MULTICALL3_ADDRESS: Hex;
+export interface MulticallCall {
+    address: Hex;
+    abi: AbiFunction[];
+    functionName: string;
+    args?: unknown[];
+    /** Per-call override of the batch allowFailure. */
+    allowFailure?: boolean;
+}
+export interface MulticallOptions {
+    /** When true (default), a reverting sub-call yields null instead of throwing the batch. */
+    allowFailure?: boolean;
+    /** Override the Multicall3 address (e.g. a local Anvil predeploy). */
+    multicallAddress?: Hex;
+    block?: Hex | "latest" | "pending";
+}
+/** Minimal Chain surface multicall needs — just the JSON-RPC passthrough. */
+interface RpcLike {
+    rpc<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+}
+/**
+ * Encode N reads into one aggregate3 eth_call and decode each result against its
+ * own function ABI. Returns one entry per input call (null for a reverted call
+ * when allowFailure). Throws on a reverted call when allowFailure is false.
+ */
+export declare function multicall(chain: RpcLike, calls: MulticallCall[], opts?: MulticallOptions): Promise<(unknown | null)[]>;
+export {};

package/dist/multicall.js

@@ -0,0 +1,65 @@
+// Multicall — batch many contract reads into one eth_call via Multicall3's
+// aggregate3. Encodes/decodes with the same abi.ts coder the rest of the runtime
+// uses (no new deps). Multicall3 is deployed at the canonical address on virtually
+// every EVM chain; pass `multicallAddress` for exotic/local chains where it isn't.
+import { decodeFunctionResult, decodeParameters, encodeFunctionData, encodeParameters, findFunction, functionSelector, } from "./abi.js";
+import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+/** Canonical Multicall3 (same address on mainnet, testnets, L2s, …). */
+export const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+// aggregate3((address target, bool allowFailure, bytes callData)[])
+//   returns ((bool success, bytes returnData)[])
+const AGGREGATE3_INPUTS = [
+    {
+        type: "tuple[]",
+        components: [
+            { name: "target", type: "address" },
+            { name: "allowFailure", type: "bool" },
+            { name: "callData", type: "bytes" },
+        ],
+    },
+];
+const AGGREGATE3_OUTPUTS = [
+    {
+        type: "tuple[]",
+        components: [
+            { name: "success", type: "bool" },
+            { name: "returnData", type: "bytes" },
+        ],
+    },
+];
+// Computed once from the canonical signature — single source of truth with abi.ts.
+const AGGREGATE3_SELECTOR = functionSelector("aggregate3((address,bool,bytes)[])");
+/**
+ * Encode N reads into one aggregate3 eth_call and decode each result against its
+ * own function ABI. Returns one entry per input call (null for a reverted call
+ * when allowFailure). Throws on a reverted call when allowFailure is false.
+ */
+export async function multicall(chain, calls, opts = {}) {
+    if (calls.length === 0)
+        return [];
+    const batchAllow = opts.allowFailure ?? true;
+    const fns = [];
+    const tuples = calls.map((c) => {
+        const fn = findFunction(c.abi, c.functionName);
+        fns.push(fn);
+        return {
+            target: c.address,
+            allowFailure: c.allowFailure ?? batchAllow,
+            callData: encodeFunctionData(fn, c.args ?? []),
+        };
+    });
+    const data = bytesToHex(concatBytes(AGGREGATE3_SELECTOR, encodeParameters(AGGREGATE3_INPUTS, [tuples])));
+    const result = await chain.rpc("eth_call", [
+        { to: opts.multicallAddress ?? MULTICALL3_ADDRESS, data },
+        opts.block ?? "latest",
+    ]);
+    const [rows] = decodeParameters(AGGREGATE3_OUTPUTS, hexToBytes(result));
+    return rows.map((row, i) => {
+        if (!row.success) {
+            if (calls[i].allowFailure ?? batchAllow)
+                return null;
+            throw new Error(`multicall: ${calls[i].functionName} on ${calls[i].address} reverted`);
+        }
+        return decodeFunctionResult(fns[i], hexToBytes(row.returnData));
+    });
+}

package/dist/queue.d.ts

@@ -0,0 +1,27 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/** Binding-name form of a queue name: upper-snake (QUEUE_<THIS>_URL/TOKEN). */
+export declare function queueEnvKey(name: string): string;
+export declare class Queue {
+    readonly name: string;
+    private readonly url?;
+    private readonly token?;
+    constructor(env: MinimalEnv | undefined, name: string);
+    /** True when the producer bindings for this queue were injected. */
+    get configured(): boolean;
+    /** Publish one message. */
+    send(message: unknown): Promise<{
+        ok: boolean;
+        queued?: number;
+    }>;
+    /** Publish many messages in one request. */
+    sendBatch(messages: unknown[]): Promise<{
+        ok: boolean;
+        queued?: number;
+    }>;
+    private post;
+}
+/** Convenience: `await queue(env, "settler").send(msg)`. */
+export declare function queue(env: MinimalEnv | undefined, name: string): Queue;
+export {};

package/dist/queue.js

@@ -0,0 +1,49 @@
+// Queue — a producer handle for a Livo per-project queue (docs/QUEUES-SPEC.md). A
+// deployable that declares `produces: [name]` gets QUEUE_<NAME>_URL +
+// QUEUE_<NAME>_TOKEN injected at deploy; this wraps them so a keeper/bot/server just
+// does `queue(env, "name").send(msg)` — no URL or token handling. The consumer then
+// batches the messages to its consume(batch, env).
+/** Binding-name form of a queue name: upper-snake (QUEUE_<THIS>_URL/TOKEN). */
+export function queueEnvKey(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+export class Queue {
+    name;
+    url;
+    token;
+    constructor(env, name) {
+        this.name = name;
+        const k = queueEnvKey(name);
+        this.url = env?.[`QUEUE_${k}_URL`];
+        this.token = env?.[`QUEUE_${k}_TOKEN`];
+    }
+    /** True when the producer bindings for this queue were injected. */
+    get configured() {
+        return Boolean(this.url && this.token);
+    }
+    /** Publish one message. */
+    send(message) {
+        return this.post(message);
+    }
+    /** Publish many messages in one request. */
+    sendBatch(messages) {
+        return this.post(messages);
+    }
+    async post(body) {
+        if (!this.url || !this.token) {
+            throw new Error(`queue "${this.name}" not configured — add it to this deployable's \`produces:\` so QUEUE_${queueEnvKey(this.name)}_URL/TOKEN are injected`);
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`queue "${this.name}" send failed: HTTP ${res.status}`);
+        return (await res.json());
+    }
+}
+/** Convenience: `await queue(env, "settler").send(msg)`. */
+export function queue(env, name) {
+    return new Queue(env, name);
+}

package/dist/secret.d.ts

@@ -0,0 +1,15 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/**
+ * Read a required secret/binding off `env`, throwing a clear error when it's
+ * missing or empty. Use at the top of a handler so misconfiguration fails fast:
+ *
+ *   const token = requireSecret(env, "BOT_TOKEN");
+ */
+export declare function requireSecret(env: MinimalEnv | undefined, name: string): string;
+/** Read an optional secret/binding, returning `fallback` (default undefined) when absent or empty. */
+export declare function getSecret(env: MinimalEnv | undefined, name: string, fallback?: string): string | undefined;
+/** Assert several secrets are present at once; throws listing ALL missing ones. */
+export declare function requireSecrets<K extends string>(env: MinimalEnv | undefined, names: readonly K[]): Record<K, string>;
+export {};

package/dist/secret.js

@@ -0,0 +1,40 @@
+// Typed secret access. Project secrets (set_secret) and auto-injected bindings
+// arrive on the Worker `env`. Reading them raw means a missing one is `undefined`
+// and silently disables a feature at runtime (the classic "my Telegram send did
+// nothing" bug). `requireSecret` turns that into a loud, actionable error the
+// moment the code runs, instead of a silent no-op.
+/**
+ * Read a required secret/binding off `env`, throwing a clear error when it's
+ * missing or empty. Use at the top of a handler so misconfiguration fails fast:
+ *
+ *   const token = requireSecret(env, "BOT_TOKEN");
+ */
+export function requireSecret(env, name) {
+    const v = env?.[name];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    throw new Error(`missing secret "${name}" — set it with set_secret ${name}=<value> (or, for an ` +
+        `auto-injected binding like KEEPER_PRIVATE_KEY/RPC_URL, check it's wired for this deployable).`);
+}
+/** Read an optional secret/binding, returning `fallback` (default undefined) when absent or empty. */
+export function getSecret(env, name, fallback) {
+    const v = env?.[name];
+    return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+/** Assert several secrets are present at once; throws listing ALL missing ones. */
+export function requireSecrets(env, names) {
+    const out = {};
+    const missing = [];
+    for (const n of names) {
+        const v = env?.[n];
+        if (typeof v === "string" && v.length > 0)
+            out[n] = v;
+        else
+            missing.push(n);
+    }
+    if (missing.length) {
+        throw new Error(`missing secret${missing.length > 1 ? "s" : ""} ${missing.map((m) => `"${m}"`).join(", ")} — ` +
+            `set with set_secret (e.g. set_secret ${missing[0]}=<value>).`);
+    }
+    return out;
+}

package/dist/store.d.ts

@@ -28,4 +28,15 @@ export declare class Store {
     getJSON<T>(key: string): Promise<T | null>;
     /** Upsert a JSON-serialized value. */
     setJSON<T>(key: string, value: T): Promise<void>;
+    /**
+     * Idempotency guard. Returns `true` the FIRST time a key is seen (claim it and
+     * proceed) and `false` on every later call — so a retried cron tick or a
+     * redelivered webhook doesn't double-fire:
+     *
+     *   if (!(await store.once(`block:${n}`))) return; // already processed n
+     *
+     * Atomic via `INSERT … ON CONFLICT DO NOTHING` + the row-changed count, so two
+     * concurrent calls can't both win.
+     */
+    once(key: string): Promise<boolean>;
 }

package/dist/store.js

@@ -57,4 +57,28 @@ export class Store {
     async setJSON(key, value) {
         await this.set(key, JSON.stringify(value));
     }
+    /**
+     * Idempotency guard. Returns `true` the FIRST time a key is seen (claim it and
+     * proceed) and `false` on every later call — so a retried cron tick or a
+     * redelivered webhook doesn't double-fire:
+     *
+     *   if (!(await store.once(`block:${n}`))) return; // already processed n
+     *
+     * Atomic via `INSERT … ON CONFLICT DO NOTHING` + the row-changed count, so two
+     * concurrent calls can't both win.
+     */
+    async once(key) {
+        await this.init();
+        const res = (await this.db
+            .prepare(`INSERT INTO ${this.table} (k, v, updated_at) VALUES (?, '1', ?)
+         ON CONFLICT(k) DO NOTHING`)
+            .bind(key, Date.now())
+            .run());
+        // D1 reports affected rows on `meta.changes` (or `changes`); 1 ⇒ we inserted.
+        const changes = res?.meta?.changes ?? res?.changes;
+        if (typeof changes === "number")
+            return changes > 0;
+        // Driver didn't surface a count — fall back to a read (non-atomic, best effort).
+        return (await this.get(key)) === "1";
+    }
 }

package/dist/telegram.d.ts

@@ -0,0 +1,63 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface TelegramOptions {
+    /** env key for the bot token. Default "BOT_TOKEN". */
+    tokenSecret?: string;
+    /** env key for the webhook secret token. Default "WEBHOOK_SECRET". */
+    webhookSecretKey?: string;
+    /** Override the token directly. */
+    token?: string;
+    /** Override the webhook secret directly. */
+    webhookSecret?: string;
+}
+/** A parsed inbound message — the shape a reply handler actually wants. */
+export interface BotMessage {
+    /** Trimmed message text. */
+    text: string;
+    /** Chat to reply into. */
+    chatId: number | string;
+    /** Sender attribution: "@username" or the numeric id as a string. */
+    handle: string;
+    /** Raw Telegram `from` object (id, username, first_name, …). */
+    from: Record<string, unknown> | undefined;
+    /** Raw Telegram message object. */
+    raw: Record<string, unknown>;
+    /** True when this came from Livo's test_bot harness (not real Telegram). */
+    isTest: boolean;
+}
+export interface SendMessageOptions {
+    parseMode?: "Markdown" | "MarkdownV2" | "HTML" | null;
+    replyToMessageId?: number;
+    disablePreview?: boolean;
+}
+export declare class Telegram {
+    private readonly token?;
+    private readonly webhookSecret?;
+    constructor(env: MinimalEnv | undefined, options?: TelegramOptions);
+    /** True when a bot token is configured (sends will actually reach Telegram). */
+    get configured(): boolean;
+    /**
+     * Verify a request really came from Telegram (or Livo's test_bot) by matching
+     * the secret-token header against WEBHOOK_SECRET. Returns true when no secret is
+     * configured (nothing to check). Use it if you parse the update yourself.
+     */
+    verify(req: Request): boolean;
+    /** Parse a raw Telegram update into a BotMessage, or null if it has no text message. */
+    parse(update: Record<string, unknown>): BotMessage | null;
+    /**
+     * Full webhook handler: verifies the secret, parses the update, runs `reply`,
+     * and either returns the computed reply to test_bot (__livo_test) or sends it to
+     * Telegram. `reply` returns a string to send, or null/undefined to stay silent.
+     * Returns the Worker Response — `return new Telegram(env).handleUpdate(req, fn)`.
+     */
+    handleUpdate(req: Request, reply: (msg: BotMessage) => string | null | undefined | Promise<string | null | undefined>, opts?: SendMessageOptions): Promise<Response>;
+    /** Send a message to a chat. No-op-safe: throws if no token is configured. */
+    sendMessage(chatId: number | string, text: string, opts?: SendMessageOptions): Promise<void>;
+    /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
+    setMyCommands(commands: Array<{
+        command: string;
+        description: string;
+    }>): Promise<void>;
+}
+export {};

package/dist/telegram.js

@@ -0,0 +1,115 @@
+// Telegram — collapses the webhook plumbing every Livo bot re-implements by hand:
+// the secret-token gate, the `__livo_test` short-circuit (so test_bot can read a
+// reply without hitting Telegram), update parsing, and the sendMessage call. A bot
+// becomes just its reply logic:
+//
+//   import { Telegram } from "@livo-build/runtime";
+//   export default {
+//     fetch(req, env) {
+//       return new Telegram(env).handleUpdate(req, (msg) =>
+//         msg.text === "/start" ? "👋 hi" : "you said " + msg.text);
+//     },
+//   };
+//
+// The deploy injects env.BOT_TOKEN (the resolved Telegram token) and
+// env.WEBHOOK_SECRET (authenticates Telegram's calls) — same bindings the
+// hand-rolled templates read.
+const API = "https://api.telegram.org/bot";
+export class Telegram {
+    token;
+    webhookSecret;
+    constructor(env, options = {}) {
+        this.token = options.token ?? env?.[options.tokenSecret ?? "BOT_TOKEN"];
+        this.webhookSecret =
+            options.webhookSecret ?? env?.[options.webhookSecretKey ?? "WEBHOOK_SECRET"];
+    }
+    /** True when a bot token is configured (sends will actually reach Telegram). */
+    get configured() {
+        return Boolean(this.token);
+    }
+    /**
+     * Verify a request really came from Telegram (or Livo's test_bot) by matching
+     * the secret-token header against WEBHOOK_SECRET. Returns true when no secret is
+     * configured (nothing to check). Use it if you parse the update yourself.
+     */
+    verify(req) {
+        if (!this.webhookSecret)
+            return true;
+        return req.headers.get("x-telegram-bot-api-secret-token") === this.webhookSecret;
+    }
+    /** Parse a raw Telegram update into a BotMessage, or null if it has no text message. */
+    parse(update) {
+        const msg = (update.message ?? update.edited_message);
+        const text = msg && typeof msg.text === "string" ? msg.text : undefined;
+        if (!msg || text === undefined)
+            return null;
+        const from = msg.from;
+        const username = from && typeof from.username === "string" ? from.username : undefined;
+        const handle = username ? `@${username}` : from?.id != null ? String(from.id) : "anon";
+        const chat = msg.chat;
+        return {
+            text: text.trim(),
+            chatId: chat?.id ?? 0,
+            handle,
+            from,
+            raw: msg,
+            isTest: update.__livo_test === true,
+        };
+    }
+    /**
+     * Full webhook handler: verifies the secret, parses the update, runs `reply`,
+     * and either returns the computed reply to test_bot (__livo_test) or sends it to
+     * Telegram. `reply` returns a string to send, or null/undefined to stay silent.
+     * Returns the Worker Response — `return new Telegram(env).handleUpdate(req, fn)`.
+     */
+    async handleUpdate(req, reply, opts = {}) {
+        if (req.method !== "POST")
+            return new Response("ok");
+        if (!this.verify(req))
+            return new Response("forbidden", { status: 403 });
+        const update = (await req.json().catch(() => ({})));
+        const msg = this.parse(update);
+        if (!msg)
+            return new Response("ok");
+        const out = (await reply(msg)) ?? null;
+        if (msg.isTest) {
+            return new Response(JSON.stringify({ reply: out }), {
+                headers: { "content-type": "application/json" },
+            });
+        }
+        if (out != null && this.configured) {
+            await this.sendMessage(msg.chatId, out, opts);
+        }
+        return new Response("ok");
+    }
+    /** Send a message to a chat. No-op-safe: throws if no token is configured. */
+    async sendMessage(chatId, text, opts = {}) {
+        if (!this.token) {
+            throw new Error("Telegram: no bot token — set it with set_secret BOT_TOKEN=<token> (the deploy injects it as env.BOT_TOKEN).");
+        }
+        const body = { chat_id: chatId, text };
+        if (opts.parseMode !== null)
+            body.parse_mode = opts.parseMode ?? "Markdown";
+        if (opts.replyToMessageId)
+            body.reply_to_message_id = opts.replyToMessageId;
+        if (opts.disablePreview)
+            body.disable_web_page_preview = true;
+        const res = await fetch(`${API}${this.token}/sendMessage`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`Telegram sendMessage failed: HTTP ${res.status}`);
+    }
+    /** Register the slash-command menu (setMyCommands) — autocompletes in chat. */
+    async setMyCommands(commands) {
+        if (!this.token)
+            throw new Error("Telegram: no bot token (set_secret BOT_TOKEN=<token>).");
+        await fetch(`${API}${this.token}/setMyCommands`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ commands }),
+        });
+    }
+}

package/dist/watch.d.ts

@@ -0,0 +1,44 @@
+import type { Chain } from "./chain.js";
+import type { Store } from "./store.js";
+import type { AbiEvent, DecodedLog } from "./events.js";
+import type { Hex } from "./hex.js";
+export interface WatchLogsOptions {
+    /** Event to decode — an AbiEvent or a human-readable signature. */
+    event: AbiEvent | string;
+    /** Contract address(es) to filter (omit to match any). */
+    address?: Hex | Hex[];
+    /** Indexed-arg filter, positional or by name (see Chain.getLogs). */
+    args?: Record<string, unknown> | unknown[];
+    /** Store key holding this watcher's cursor. Namespace it per watcher. */
+    cursorKey: string;
+    /** First block to scan when no cursor exists yet. Default: current head (new logs only). */
+    fromBlock?: bigint;
+    /** Stay this many blocks behind head for reorg safety. Default 0. */
+    confirmations?: bigint;
+    /** Max blocks per eth_getLogs window (RPC range cap). Default 2000n. */
+    chunkSize?: bigint;
+    /** Invoked per non-empty chunk with that chunk's decoded logs. Must be idempotent. */
+    onLogs: (logs: DecodedLog[], range: {
+        fromBlock: bigint;
+        toBlock: bigint;
+    }) => Promise<void> | void;
+}
+export interface WatchLogsResult {
+    /** First block scanned this run. */
+    fromBlock: bigint;
+    /** New cursor — the last block scanned (head - confirmations). */
+    toBlock: bigint;
+    /** Total logs delivered to onLogs this run. */
+    logCount: number;
+    /** Number of eth_getLogs windows scanned. */
+    chunks: number;
+}
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export declare function watchLogs(chain: Chain, store: Store, opts: WatchLogsOptions): Promise<WatchLogsResult>;

package/dist/watch.js

@@ -0,0 +1,46 @@
+// watchLogs — resumable event catch-up for keepers. A Worker has no long-lived
+// process, so this is NOT a websocket subscription: each scheduled tick reads new
+// logs since a Store-persisted block cursor, up to the (confirmed) head, in
+// chunked eth_getLogs windows. Layered as a free function over Chain + Store so
+// Chain (Layer 1, may hold keys) never imports Store (Layer 3).
+/**
+ * Catch up on event logs since the last run. Reads the cursor (or `fromBlock`),
+ * scans `[cursor, head - confirmations]` in `chunkSize` windows, calls `onLogs`
+ * per non-empty chunk, and persists the cursor AFTER each chunk — so a Worker
+ * killed mid-catch-up resumes from the last completed window. Delivery is
+ * at-least-once: if `onLogs` throws, the cursor is not advanced past that chunk
+ * and the next tick retries it, so `onLogs` must be idempotent.
+ */
+export async function watchLogs(chain, store, opts) {
+    const confirmations = opts.confirmations ?? 0n;
+    const chunkSize = opts.chunkSize ?? 2000n;
+    const head = await chain.getBlockNumber();
+    const safeHead = head - confirmations;
+    const stored = await store.getJSON(opts.cursorKey);
+    const from = stored ? BigInt(stored.next) : (opts.fromBlock ?? safeHead);
+    if (from > safeHead) {
+        return { fromBlock: from, toBlock: from - 1n, logCount: 0, chunks: 0 };
+    }
+    let cur = from;
+    let logCount = 0;
+    let chunks = 0;
+    while (cur <= safeHead) {
+        const to = cur + chunkSize - 1n < safeHead ? cur + chunkSize - 1n : safeHead;
+        const logs = await chain.getLogs({
+            event: opts.event,
+            address: opts.address,
+            args: opts.args,
+            fromBlock: cur,
+            toBlock: to,
+        });
+        chunks++;
+        if (logs.length) {
+            await opts.onLogs(logs, { fromBlock: cur, toBlock: to });
+            logCount += logs.length;
+        }
+        // Advance + persist only after a successful onLogs, so a throw retries this window.
+        await store.setJSON(opts.cursorKey, { next: (to + 1n).toString() });
+        cur = to + 1n;
+    }
+    return { fromBlock: from, toBlock: safeHead, logCount, chunks };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",