@livo-build/runtime 0.2.4 → 0.2.6

package/dist/telegram.js

@@ -132,4 +132,77 @@ export class Telegram {
             body: JSON.stringify({ commands }),
         });
     }
+    // ---- Group / membership management (token-gated rooms) --------------------
+    // Generic Bot API call: POST JSON, return result, throw on Telegram error.
+    async api(method, body) {
+        if (!this.token)
+            throw new Error("Telegram: no bot token (set_secret TELEGRAM_BOT_TOKEN=<token>).");
+        const res = await fetch(`${API}${this.token}/${method}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const j = (await res.json().catch(() => null));
+        if (!res.ok || !j?.ok)
+            throw new Error(`Telegram ${method} failed: ${j?.description ?? "HTTP " + res.status}`);
+        return j.result;
+    }
+    /** Parse a `chat_join_request` update (a user asking to join a join-request chat). */
+    joinRequest(update) {
+        const r = update.chat_join_request;
+        if (!r)
+            return null;
+        const from = r.from;
+        const chat = r.chat;
+        if (!from || !chat)
+            return null;
+        return {
+            chatId: chat.id,
+            userId: from.id,
+            username: from.username,
+            from,
+            raw: r,
+        };
+    }
+    /** Admit a pending join request. */
+    approveJoinRequest(chatId, userId) {
+        return this.api("approveChatJoinRequest", { chat_id: chatId, user_id: userId });
+    }
+    /** Reject a pending join request. */
+    declineJoinRequest(chatId, userId) {
+        return this.api("declineChatJoinRequest", { chat_id: chatId, user_id: userId });
+    }
+    /** Remove (ban) a member — the "boot" when they no longer qualify. */
+    banMember(chatId, userId, opts = {}) {
+        return this.api("banChatMember", {
+            chat_id: chatId,
+            user_id: userId,
+            ...(opts.untilDate ? { until_date: opts.untilDate } : {}),
+            ...(opts.revokeMessages ? { revoke_messages: true } : {}),
+        });
+    }
+    /** Lift a ban so a re-qualified user can rejoin (does NOT add them back). */
+    unbanMember(chatId, userId, opts = { onlyIfBanned: true }) {
+        return this.api("unbanChatMember", { chat_id: chatId, user_id: userId, only_if_banned: opts.onlyIfBanned !== false });
+    }
+    /** Create an invite link. With createsJoinRequest, joins need bot approval (the gate). */
+    async createInviteLink(chatId, opts = {}) {
+        const result = (await this.api("createChatInviteLink", {
+            chat_id: chatId,
+            ...(opts.name ? { name: opts.name } : {}),
+            ...(opts.createsJoinRequest ? { creates_join_request: true } : {}),
+            ...(opts.expireDate ? { expire_date: opts.expireDate } : {}),
+        }));
+        return result.invite_link ?? "";
+    }
+    /** A member's status in a chat ("member" | "left" | "kicked" | "administrator" | "creator" | "restricted"). */
+    async memberStatus(chatId, userId) {
+        try {
+            const result = (await this.api("getChatMember", { chat_id: chatId, user_id: userId }));
+            return result.status ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
 }

package/dist/telegramAuth.d.ts

@@ -0,0 +1,16 @@
+export interface TelegramUser {
+    id: number;
+    username?: string;
+    firstName?: string;
+    lastName?: string;
+    languageCode?: string;
+    isPremium?: boolean;
+    photoUrl?: string;
+}
+export interface VerifyOptions {
+    /** Reject if auth_date is older than this many seconds (0 = no check). Default 86400. */
+    maxAgeSeconds?: number;
+}
+export declare function verifyTelegramInitData(initData: string, botToken: string, options?: VerifyOptions): Promise<TelegramUser | null>;
+export declare function verifyTelegramLoginWidget(data: Record<string, string | number | undefined>, botToken: string, options?: VerifyOptions): Promise<TelegramUser | null>;
+export declare function parseStartPayload(text: string): string | null;

package/dist/telegramAuth.js

@@ -0,0 +1,108 @@
+// Telegram identity verification — the security core of linking a Telegram user to
+// a wallet. Runs server-side (bot token never leaves the server). Two sources:
+//   • Mini App initData  — verifyTelegramInitData (HMAC keyed by "WebAppData")
+//   • Login Widget data   — verifyTelegramLoginWidget (HMAC keyed by SHA256(token))
+// Both follow Telegram's documented algorithm exactly: build a data_check_string of
+// the fields (sorted, key=value, "\n"-joined, EXCLUDING `hash`), HMAC-SHA256 it, and
+// constant-time compare to the provided `hash`. Web Crypto only (Worker-safe).
+// Bare lowercase hex (NO "0x" prefix) — Telegram's `hash` is bare hex, so we must
+// not use the chain-style bytesToHex (which prefixes "0x").
+function toHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++)
+        out += bytes[i].toString(16).padStart(2, "0");
+    return out;
+}
+const enc = (s) => new TextEncoder().encode(s);
+async function hmacSha256(keyBytes, msg) {
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, msg));
+}
+async function sha256(bytes) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+}
+// Constant-time-ish hex compare (avoids leaking the match position).
+function safeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function freshEnough(authDate, maxAgeSeconds) {
+    if (maxAgeSeconds <= 0)
+        return true;
+    if (!authDate)
+        return false;
+    return Math.floor(Date.now() / 1000) - authDate <= maxAgeSeconds;
+}
+function userFromRaw(u) {
+    return {
+        id: Number(u.id),
+        username: u.username,
+        firstName: u.first_name,
+        lastName: u.last_name,
+        languageCode: u.language_code,
+        isPremium: u.is_premium,
+        photoUrl: u.photo_url,
+    };
+}
+// Verify Telegram Mini App `initData` (the raw query string from
+// window.Telegram.WebApp.initData). Returns the verified user, or null.
+export async function verifyTelegramInitData(initData, botToken, options = {}) {
+    if (!initData || !botToken)
+        return null;
+    const params = new URLSearchParams(initData);
+    const hash = params.get("hash");
+    if (!hash)
+        return null;
+    params.delete("hash");
+    const dataCheckString = [...params.entries()]
+        .map(([k, v]) => `${k}=${v}`)
+        .sort()
+        .join("\n");
+    // secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)
+    const secretKey = await hmacSha256(enc("WebAppData"), enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, hash))
+        return null;
+    if (!freshEnough(Number(params.get("auth_date") ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    const userJson = params.get("user");
+    if (!userJson)
+        return null;
+    try {
+        return userFromRaw(JSON.parse(userJson));
+    }
+    catch {
+        return null;
+    }
+}
+// Verify Telegram Login Widget data (the object the widget hands your page, with a
+// `hash`). Returns the verified user, or null.
+export async function verifyTelegramLoginWidget(data, botToken, options = {}) {
+    const hash = data.hash;
+    if (!hash || !botToken)
+        return null;
+    const dataCheckString = Object.keys(data)
+        .filter((k) => k !== "hash" && data[k] !== undefined)
+        .sort()
+        .map((k) => `${k}=${data[k]}`)
+        .join("\n");
+    // secret_key = SHA256(bot_token) (NOTE: plain SHA-256 here, not HMAC).
+    const secretKey = await sha256(enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, String(hash)))
+        return null;
+    if (!freshEnough(Number(data.auth_date ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    return userFromRaw(data);
+}
+// Pull the payload from a `/start <payload>` deep-link command (the non-Mini-App
+// linking flow). Returns the trimmed payload, or null.
+export function parseStartPayload(text) {
+    const m = /^\/start(?:@\w+)?(?:\s+(.+))?$/.exec(text.trim());
+    const payload = m?.[1]?.trim();
+    return payload ? payload : null;
+}

package/dist/telegramAuth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telegramAuth.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { createHmac, createHash } from "node:crypto";
+import { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+const BOT_TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11";
+const USER = { id: 42, username: "alice", first_name: "Alice", language_code: "en" };
+// Build a valid Mini App initData the way Telegram does — using node:crypto, an
+// INDEPENDENT implementation from the verifier's Web Crypto. Agreement = correct.
+function makeInitData(botToken, authDate, user = USER) {
+    const params = new URLSearchParams();
+    params.set("user", JSON.stringify(user));
+    params.set("auth_date", String(authDate));
+    params.set("query_id", "AAH-test");
+    const dcs = [...params.entries()].map(([k, v]) => `${k}=${v}`).sort().join("\n");
+    const secret = createHmac("sha256", "WebAppData").update(botToken).digest();
+    const hash = createHmac("sha256", secret).update(dcs).digest("hex");
+    params.set("hash", hash);
+    return params.toString();
+}
+const now = () => Math.floor(Date.now() / 1000);
+describe("verifyTelegramInitData", () => {
+    it("accepts a valid initData and returns the user", async () => {
+        const u = await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), BOT_TOKEN);
+        expect(u).not.toBeNull();
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+        expect(u?.firstName).toBe("Alice");
+    });
+    it("rejects a tampered hash", async () => {
+        const good = makeInitData(BOT_TOKEN, now());
+        const tampered = good.replace(/hash=([0-9a-f])/, (_, c) => `hash=${c === "0" ? "1" : "0"}`);
+        expect(await verifyTelegramInitData(tampered, BOT_TOKEN)).toBeNull();
+    });
+    it("rejects the wrong bot token", async () => {
+        expect(await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), "999:WRONG")).toBeNull();
+    });
+    it("rejects stale auth_date", async () => {
+        const old = makeInitData(BOT_TOKEN, now() - 100_000);
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 3600 })).toBeNull();
+        // ...but accepts it when the age check is disabled.
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 0 })).not.toBeNull();
+    });
+    it("rejects empty / hashless input", async () => {
+        expect(await verifyTelegramInitData("", BOT_TOKEN)).toBeNull();
+        expect(await verifyTelegramInitData("user=%7B%7D&auth_date=1", BOT_TOKEN)).toBeNull();
+    });
+});
+describe("verifyTelegramLoginWidget", () => {
+    it("accepts valid widget data (SHA256(token) secret)", async () => {
+        const data = { id: 42, username: "alice", auth_date: now() };
+        const dcs = Object.keys(data).sort().map((k) => `${k}=${data[k]}`).join("\n");
+        const secret = createHash("sha256").update(BOT_TOKEN).digest();
+        data.hash = createHmac("sha256", secret).update(dcs).digest("hex");
+        const u = await verifyTelegramLoginWidget(data, BOT_TOKEN);
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+    });
+    it("rejects a bad hash", async () => {
+        expect(await verifyTelegramLoginWidget({ id: 1, auth_date: now(), hash: "deadbeef" }, BOT_TOKEN)).toBeNull();
+    });
+});
+describe("parseStartPayload", () => {
+    it("extracts the payload from /start", () => {
+        expect(parseStartPayload("/start link_abc123")).toBe("link_abc123");
+        expect(parseStartPayload("/start@MyBot tok")).toBe("tok");
+        expect(parseStartPayload("/start")).toBeNull();
+        expect(parseStartPayload("hello")).toBeNull();
+    });
+});

package/dist/telegramLinks.d.ts

@@ -0,0 +1,27 @@
+import type { D1Like } from "./store.js";
+export declare const TELEGRAM_LINKS_TABLE = "telegram_links";
+export interface TelegramLink {
+    telegramId: string;
+    address: string;
+    username?: string;
+    createdAt: number;
+}
+export declare class TelegramLinks {
+    private readonly db;
+    private readonly table;
+    private ready;
+    constructor(db: D1Like, table?: string);
+    private init;
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    link(telegramId: string | number, address: string, username?: string): Promise<void>;
+    /** Remove the link for a Telegram user. */
+    unlink(telegramId: string | number): Promise<void>;
+    /** The wallet address linked to a Telegram user, or null. */
+    walletFor(telegramId: string | number): Promise<string | null>;
+    /** The Telegram link for a wallet address, or null. */
+    telegramFor(address: string): Promise<TelegramLink | null>;
+    /** Whether a Telegram user has a linked wallet. */
+    isLinked(telegramId: string | number): Promise<boolean>;
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    all(limit?: number): Promise<TelegramLink[]>;
+}

package/dist/telegramLinks.js

@@ -0,0 +1,78 @@
+// TelegramLinks — the shared binding between a Telegram user and a wallet address,
+// stored in the project's D1 (env.DB, which is bound into BOTH the api Worker and
+// the bot). Write it from the api after verifying both proofs; read it from the bot
+// to answer "is this user's wallet connected?".
+export const TELEGRAM_LINKS_TABLE = "telegram_links";
+export class TelegramLinks {
+    db;
+    table;
+    ready = null;
+    constructor(db, table = TELEGRAM_LINKS_TABLE) {
+        this.db = db;
+        this.table = table;
+        if (!db)
+            throw new Error("TelegramLinks: no D1 binding — pass env.DB (is the project's D1 bound?)");
+    }
+    async init() {
+        if (!this.ready) {
+            this.ready = (async () => {
+                if (this.db.exec) {
+                    await this.db.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (telegram_id TEXT PRIMARY KEY, address TEXT NOT NULL, username TEXT, created_at INTEGER); CREATE INDEX IF NOT EXISTS ${this.table}_address ON ${this.table} (address);`);
+                }
+            })();
+        }
+        return this.ready;
+    }
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    async link(telegramId, address, username) {
+        await this.init();
+        await this.db
+            .prepare(`INSERT INTO ${this.table} (telegram_id, address, username, created_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(telegram_id) DO UPDATE SET address = excluded.address, username = excluded.username, created_at = excluded.created_at`)
+            .bind(String(telegramId), address.toLowerCase(), username ?? null, Date.now())
+            .run();
+    }
+    /** Remove the link for a Telegram user. */
+    async unlink(telegramId) {
+        await this.init();
+        await this.db.prepare(`DELETE FROM ${this.table} WHERE telegram_id = ?`).bind(String(telegramId)).run();
+    }
+    /** The wallet address linked to a Telegram user, or null. */
+    async walletFor(telegramId) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT address FROM ${this.table} WHERE telegram_id = ?`)
+            .bind(String(telegramId))
+            .first();
+        return row ? row.address : null;
+    }
+    /** The Telegram link for a wallet address, or null. */
+    async telegramFor(address) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} WHERE address = ?`)
+            .bind(address.toLowerCase())
+            .first();
+        return row
+            ? { telegramId: row.telegram_id, address: row.address, username: row.username ?? undefined, createdAt: row.created_at }
+            : null;
+    }
+    /** Whether a Telegram user has a linked wallet. */
+    async isLinked(telegramId) {
+        return (await this.walletFor(telegramId)) !== null;
+    }
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    async all(limit = 1000) {
+        await this.init();
+        const res = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} LIMIT ?`)
+            .bind(limit)
+            .all();
+        return (res.results ?? []).map((r) => ({
+            telegramId: r.telegram_id,
+            address: r.address,
+            username: r.username ?? undefined,
+            createdAt: r.created_at,
+        }));
+    }
+}

package/dist/watcher.d.ts

@@ -0,0 +1,83 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+/** Bindings the platform injects into a deployed watcher Worker. */
+export interface WatcherEnv extends MinimalEnv {
+    LIVO_WATCHER_DISPATCH_TOKEN?: string;
+    LIVO_SIGNAL_SUBSCRIBE_URL?: string;
+    LIVO_SIGNAL_CANCEL_URL?: string;
+    LIVO_WATCHER_URL?: string;
+    LIVO_PROJECT_ID?: string;
+    LIVO_WATCHER_NAME?: string;
+    LIVO_CHAIN_ID?: string;
+    LIVO_RUN_URL?: string;
+    LIVO_RUN_TOKEN?: string;
+}
+export type Confidence = "high" | "medium" | "low" | "none";
+export type MatchStatus = "confirmed" | "reverted";
+/** A delivered match (the engine-emitted, priced event that fired a signal). */
+export interface WatcherMatch {
+    deliveryKey: string;
+    matchKey: string;
+    status: MatchStatus;
+    signalId: string;
+    subId: number;
+    watcherId: number;
+    market: {
+        base: string;
+        quote: string;
+        pool: string;
+    };
+    event: {
+        actor: string;
+        kind: string;
+        ts: number;
+        amountUsdMicros: number | null;
+        tokenUsdMicros: number | null;
+        confidence: Confidence;
+        deviationBps: number | null;
+        eventId: {
+            blockHash: string;
+            txHash: string;
+            logIndex: number;
+        };
+    };
+}
+/** A subscription scope (token / watchlist / actor / global). */
+export interface WatcherScope {
+    kind: "token" | "watchlist" | "actor" | "global";
+    market?: string;
+    markets?: string[];
+    actor?: string;
+}
+export interface SubscribeOptions {
+    /** Stable id for this subscription (and self-cancel handle). */
+    subKey: string;
+    signalId: string;
+    scope: WatcherScope;
+    params?: Record<string, unknown>;
+    /** Where matches deliver. Defaults to this watcher's own onMatch URL. */
+    dispatchUrl?: string;
+    chain?: number;
+    /** Time-sensitive (stop-loss/take-profit) — armed immediately. Default true. */
+    ephemeral?: boolean;
+}
+/** Context passed to onMatch: env + runtime subscribe/cancel (exit-triggers). */
+export interface WatcherContext {
+    env: WatcherEnv;
+    /** Arm a new subscription now (e.g. a stop-loss at fill time). */
+    subscribe(opts: SubscribeOptions): Promise<boolean>;
+    /** Remove a subscription by its subKey (self-cancel on fire). */
+    cancel(subKey: string): Promise<boolean>;
+}
+export interface WatcherDefinition {
+    /** The signal this watcher reacts to (informational; the platform routes). */
+    signal?: string;
+    onMatch: (match: WatcherMatch, ctx: WatcherContext) => Promise<void> | void;
+}
+/** A deployable Worker module ({ fetch }) — the shape Cloudflare invokes. */
+export interface WatcherModule {
+    fetch(req: Request, env: WatcherEnv, ctx?: unknown): Promise<Response>;
+}
+export declare function defineWatcher(def: WatcherDefinition): WatcherModule;
+export {};

package/dist/watcher.js

@@ -0,0 +1,155 @@
+// defineWatcher — the watcher-facing primitive for Signal Radar (the onMatch
+// counterpart to keepers' scheduled()). A watcher is an HTTP-triggered Worker:
+// the platform delivers ONE subscription-addressed match per request to its
+// onMatch handler (SIGNAL-RADAR-IMPL-SPEC.md §10–§11).
+//
+// Auth mirrors the rest of the runtime (bearer tokens, not hand-rolled crypto):
+// each delivery carries the watcher's dispatchToken as a bearer, injected at
+// deploy as LIVO_WATCHER_DISPATCH_TOKEN. The same token authenticates this
+// watcher's ctx.subscribe()/cancel() calls. (HMAC-signing the body is a later
+// hardening step; the bearer scopes a leak to this one watcher today.)
+export function defineWatcher(def) {
+    return {
+        async fetch(req, env, _ctx) {
+            if (req.method !== "POST")
+                return jsonResponse({ error: "method_not_allowed" }, 405);
+            // Per-watcher dispatch auth. Fail closed if no token is configured.
+            const expected = env.LIVO_WATCHER_DISPATCH_TOKEN;
+            if (!expected || bearer(req) !== expected) {
+                return jsonResponse({ error: "unauthorized" }, 401);
+            }
+            let match;
+            try {
+                match = parseMatch(await req.json());
+            }
+            catch {
+                return jsonResponse({ error: "bad_request" }, 400);
+            }
+            const ctx = makeContext(env);
+            const startedAt = Date.now();
+            try {
+                await def.onMatch(match, ctx);
+                await reportRun(env, startedAt, true);
+                return jsonResponse({ ok: true }, 200);
+            }
+            catch (e) {
+                await reportRun(env, startedAt, false, String(e));
+                return jsonResponse({ ok: false }, 500);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internals.
+// ---------------------------------------------------------------------------
+function makeContext(env) {
+    const token = env.LIVO_WATCHER_DISPATCH_TOKEN ?? "";
+    return {
+        env,
+        async subscribe(opts) {
+            const url = env.LIVO_SIGNAL_SUBSCRIBE_URL;
+            if (!url)
+                return false;
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+                body: JSON.stringify({
+                    projectId: env.LIVO_PROJECT_ID,
+                    watcherName: env.LIVO_WATCHER_NAME,
+                    chain: opts.chain ?? Number(env.LIVO_CHAIN_ID ?? "1"),
+                    signalId: opts.signalId,
+                    scope: opts.scope,
+                    params: opts.params ?? {},
+                    dispatchUrl: opts.dispatchUrl ?? env.LIVO_WATCHER_URL ?? "",
+                    subKey: opts.subKey,
+                    ephemeral: opts.ephemeral ?? true,
+                }),
+            }).catch(() => undefined);
+            return Boolean(res && res.ok);
+        },
+        async cancel(subKey) {
+            const url = env.LIVO_SIGNAL_CANCEL_URL;
+            if (!url)
+                return false;
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+                body: JSON.stringify({ subKey }),
+            }).catch(() => undefined);
+            return Boolean(res && res.ok);
+        },
+    };
+}
+function bearer(req) {
+    const h = req.headers.get("authorization") ?? req.headers.get("Authorization");
+    if (!h)
+        return null;
+    const m = h.match(/^Bearer\s+(.+)$/i);
+    return m ? m[1] : null;
+}
+function jsonResponse(body, status) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** Parse the platform's wire envelope (snake_case JSON) into a typed match. */
+function parseMatch(raw) {
+    const b = raw;
+    const ev = (b.event ?? {});
+    const eid = (ev.event_id ?? {});
+    if (typeof b.delivery_key !== "string" || typeof b.match_key !== "string") {
+        throw new Error("malformed match envelope");
+    }
+    return {
+        deliveryKey: b.delivery_key,
+        matchKey: b.match_key,
+        status: b.status === "reverted" ? "reverted" : "confirmed",
+        signalId: String(b.signal_id ?? ""),
+        subId: Number(b.sub_id ?? 0),
+        watcherId: Number(b.watcher_id ?? 0),
+        market: {
+            base: String(b.market?.base ?? ""),
+            quote: String(b.market?.quote ?? ""),
+            pool: String(b.market?.pool ?? ""),
+        },
+        event: {
+            actor: String(ev.actor ?? ""),
+            kind: String(ev.kind ?? ""),
+            ts: Number(ev.ts ?? 0),
+            amountUsdMicros: numOrNull(ev.amount_usd_micros),
+            tokenUsdMicros: numOrNull(ev.token_usd_micros),
+            confidence: ev.confidence ?? "none",
+            deviationBps: numOrNull(ev.deviation_bps),
+            eventId: {
+                blockHash: String(eid.block_hash ?? ""),
+                txHash: String(eid.tx_hash ?? ""),
+                logIndex: Number(eid.log_index ?? 0),
+            },
+        },
+    };
+}
+function numOrNull(v) {
+    return typeof v === "number" ? v : null;
+}
+/** Best-effort run-log report (mirrors the keeper wrapper). Never throws. */
+async function reportRun(env, startedAt, ok, error) {
+    const url = env.LIVO_RUN_URL;
+    const token = env.LIVO_RUN_TOKEN;
+    if (!url || !token)
+        return;
+    await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+            projectId: env.LIVO_PROJECT_ID,
+            ownerKind: "watcher",
+            ownerName: env.LIVO_WATCHER_NAME,
+            trigger: "match",
+            startedAt,
+            durationMs: Date.now() - startedAt,
+            ok,
+            error,
+        }),
+    }).catch(() => undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,9 +16,19 @@
       "import": "./dist/contracts.js"
     }
   },
-  "files": ["dist"],
-  "engines": { "node": ">=18" },
-  "keywords": ["livo", "web3", "keeper", "eip1559", "evm"],
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "livo",
+    "web3",
+    "keeper",
+    "eip1559",
+    "evm"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -35,6 +45,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@nktkas/hyperliquid": "^0.33.0",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0"
   },