@livo-build/runtime 0.2.4 → 0.2.5

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.5",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",
@@ -35,6 +35,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@nktkas/hyperliquid": "^0.33.0",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0"
   },