@livo-build/runtime 0.2.12 → 0.2.13

package/dist/email.d.ts

@@ -0,0 +1,74 @@
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export interface EmailOptions {
+    /** Platform email API base, e.g. https://<site>/email. Default env EMAIL_API_URL. */
+    apiUrl?: string;
+    /** Bearer scoping calls to this project. Default env EMAIL_API_TOKEN. */
+    apiToken?: string;
+}
+export type EmailDirection = "in" | "out";
+/** One message in the project's inbox/outbox (newest first from `list`). */
+export interface EmailMessage {
+    id: string;
+    direction: EmailDirection;
+    from: string;
+    to: string[];
+    cc: string[];
+    subject: string;
+    text: string | null;
+    html: string | null;
+    messageId: string | null;
+    inReplyTo: string | null;
+    read: boolean;
+    receivedAt: number;
+}
+export interface ListEmailsOptions {
+    /** Only unread inbound/outbound messages. */
+    unread?: boolean;
+    /** Max messages to return (1–100, default 20). */
+    limit?: number;
+}
+export interface SendEmailOptions {
+    to: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    /** Display name for the From (address is always the project's own). */
+    fromName?: string;
+    /** Message-ID this is replying to (sets In-Reply-To/References for threading). */
+    inReplyTo?: string;
+}
+export interface SendEmailResult {
+    ok: boolean;
+    message_id: string | null;
+}
+export declare class Email {
+    private readonly apiUrl?;
+    private readonly apiToken?;
+    constructor(env: MinimalEnv | undefined, options?: EmailOptions);
+    /** Recent messages, newest first. Defaults to the whole inbox+outbox (20). */
+    list(opts?: ListEmailsOptions): Promise<EmailMessage[]>;
+    /** Unread inbound messages, newest first (shorthand for list({ unread: true })). */
+    unread(limit?: number): Promise<EmailMessage[]>;
+    /** Fetch one message by id (full body). Returns null if it isn't in this inbox. */
+    get(id: string): Promise<EmailMessage | null>;
+    /** Mark a message read (or unread with read=false). */
+    markRead(id: string, read?: boolean): Promise<void>;
+    /** Send a new message AS the project ({slug}@livo.build). */
+    send(opts: SendEmailOptions): Promise<SendEmailResult>;
+    /**
+     * Reply to an inbound message: sends back to its sender, threads via Message-ID,
+     * prefixes "Re:" if needed, and marks the original read. Pass `to` to override
+     * the recipient.
+     */
+    reply(msg: EmailMessage, opts: {
+        text?: string;
+        html?: string;
+        fromName?: string;
+        to?: string | string[];
+    }): Promise<SendEmailResult>;
+    /** Internal: call an email API sub-path with the project bearer; throws on error. */
+    private call;
+}
+export {};

package/dist/email.js

@@ -0,0 +1,100 @@
+// Email — the project's own inbox at {slug}@livo.build. Every Livo project gets a
+// canonical address; this helper lets a deployed bot/server/keeper read incoming
+// mail and send (or reply) AS the project, with zero key/SMTP handling. All calls
+// go to the platform (EMAIL_API_URL, authorized by EMAIL_API_TOKEN, both injected
+// at deploy); inbound is parsed + stored by the platform Email Worker, and sends
+// go out through the platform's transactional provider — so a leaked Worker can
+// only send AS this project, never spoof another.
+//
+//   const email = new Email(env);
+//   const inbox = await email.list({ unread: true });   // newest first
+//   for (const m of inbox) {
+//     const full = await email.get(m.id);                // full body
+//     await email.reply(full, { text: "thanks!" });      // sends + marks read
+//   }
+//   await email.send({ to: "a@b.com", subject: "hi", text: "hello" });
+//
+// The From address is always the project's own ({slug}@livo.build) — pass
+// `fromName` for a display name. To poll on a schedule, call list() from a keeper;
+// to react instantly, point a webhook at your api/ Worker (see livo://skill/email).
+export class Email {
+    apiUrl;
+    apiToken;
+    constructor(env, options = {}) {
+        this.apiUrl = (options.apiUrl ?? env?.EMAIL_API_URL)?.replace(/\/$/, "");
+        this.apiToken = options.apiToken ?? env?.EMAIL_API_TOKEN;
+    }
+    /** Recent messages, newest first. Defaults to the whole inbox+outbox (20). */
+    async list(opts = {}) {
+        const qs = new URLSearchParams();
+        if (opts.unread)
+            qs.set("unread", "1");
+        if (opts.limit)
+            qs.set("limit", String(opts.limit));
+        const r = await this.call("GET", `list${qs.toString() ? `?${qs}` : ""}`);
+        return (r.messages ?? []);
+    }
+    /** Unread inbound messages, newest first (shorthand for list({ unread: true })). */
+    async unread(limit) {
+        return this.list({ unread: true, limit });
+    }
+    /** Fetch one message by id (full body). Returns null if it isn't in this inbox. */
+    async get(id) {
+        const r = await this.call("POST", "get", { id });
+        return r.message ?? null;
+    }
+    /** Mark a message read (or unread with read=false). */
+    async markRead(id, read = true) {
+        await this.call("POST", "mark-read", { id, read });
+    }
+    /** Send a new message AS the project ({slug}@livo.build). */
+    async send(opts) {
+        const r = await this.call("POST", "send", {
+            to: Array.isArray(opts.to) ? opts.to : [opts.to],
+            subject: opts.subject,
+            text: opts.text,
+            html: opts.html,
+            fromName: opts.fromName,
+            inReplyTo: opts.inReplyTo,
+        });
+        return { ok: r.ok === true, message_id: r.message_id ?? null };
+    }
+    /**
+     * Reply to an inbound message: sends back to its sender, threads via Message-ID,
+     * prefixes "Re:" if needed, and marks the original read. Pass `to` to override
+     * the recipient.
+     */
+    async reply(msg, opts) {
+        const subject = /^re:/i.test(msg.subject) ? msg.subject : `Re: ${msg.subject}`;
+        const result = await this.send({
+            to: opts.to ?? msg.from,
+            subject,
+            text: opts.text,
+            html: opts.html,
+            fromName: opts.fromName,
+            inReplyTo: msg.messageId ?? undefined,
+        });
+        if (result.ok && !msg.read)
+            await this.markRead(msg.id).catch(() => { });
+        return result;
+    }
+    /** Internal: call an email API sub-path with the project bearer; throws on error. */
+    async call(method, path, body) {
+        if (!this.apiUrl || !this.apiToken) {
+            throw new Error("Email: not provisioned — EMAIL_API_URL/EMAIL_API_TOKEN missing (redeploy so the platform injects them).");
+        }
+        const res = await fetch(`${this.apiUrl}/${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.apiToken}`,
+                ...(body ? { "content-type": "application/json" } : {}),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const j = (await res.json().catch(() => ({})));
+        if (!res.ok || j.error) {
+            throw new Error(`Email ${path}: ${String(j.message ?? j.error ?? `HTTP ${res.status}`)}`);
+        }
+        return j;
+    }
+}

package/dist/email.test.d.ts

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

package/dist/email.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { Email } from "./email.js";
+const ENV = { EMAIL_API_URL: "https://site.example/email", EMAIL_API_TOKEN: "tok_123" };
+function mockFetch(handler) {
+    const calls = [];
+    const fn = vi.fn(async (url, init) => {
+        const call = {
+            url,
+            method: init?.method ?? "GET",
+            auth: init?.headers?.authorization ?? null,
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        };
+        calls.push(call);
+        const { status = 200, json } = handler(call);
+        return { ok: status >= 200 && status < 300, status, json: async () => json };
+    });
+    vi.stubGlobal("fetch", fn);
+    return calls;
+}
+afterEach(() => vi.unstubAllGlobals());
+describe("Email", () => {
+    it("lists newest-first, passing the bearer and unread/limit query", async () => {
+        const calls = mockFetch(() => ({ json: { ok: true, address: "p@livo.build", messages: [{ id: "e1" }] } }));
+        const email = new Email(ENV);
+        const msgs = await email.list({ unread: true, limit: 5 });
+        expect(msgs).toEqual([{ id: "e1" }]);
+        expect(calls[0].url).toBe("https://site.example/email/list?unread=1&limit=5");
+        expect(calls[0].method).toBe("GET");
+        expect(calls[0].auth).toBe("Bearer tok_123");
+    });
+    it("send wraps a single recipient into an array and reports the message id", async () => {
+        const calls = mockFetch(() => ({ json: { ok: true, message_id: "m_42" } }));
+        const email = new Email(ENV);
+        const r = await email.send({ to: "a@b.com", subject: "hi", text: "yo" });
+        expect(r).toEqual({ ok: true, message_id: "m_42" });
+        expect(calls[0].url).toBe("https://site.example/email/send");
+        expect(calls[0].body).toMatchObject({ to: ["a@b.com"], subject: "hi", text: "yo" });
+    });
+    it("reply threads via Message-ID, prefixes Re:, and marks the original read", async () => {
+        const calls = mockFetch((c) => (c.url.endsWith("/send") ? { json: { ok: true, message_id: "out1" } } : { json: { ok: true } }));
+        const msg = {
+            id: "e9", direction: "in", from: "sender@x.com", to: ["p@livo.build"], cc: [],
+            subject: "Question", text: "?", html: null, messageId: "<abc@x.com>", inReplyTo: null,
+            read: false, receivedAt: 1,
+        };
+        const email = new Email(ENV);
+        const r = await email.reply(msg, { text: "answer" });
+        expect(r.ok).toBe(true);
+        const send = calls.find((c) => c.url.endsWith("/send"));
+        expect(send.body).toMatchObject({ to: ["sender@x.com"], subject: "Re: Question", inReplyTo: "<abc@x.com>" });
+        const mark = calls.find((c) => c.url.endsWith("/mark-read"));
+        expect(mark?.body).toMatchObject({ id: "e9", read: true });
+    });
+    it("does not double-prefix Re: on an already-Re subject", async () => {
+        const calls = mockFetch(() => ({ json: { ok: true, message_id: "x" } }));
+        const msg = { id: "e", direction: "in", from: "s@x.com", to: [], cc: [], subject: "Re: Hi", text: null, html: null, messageId: null, inReplyTo: null, read: true, receivedAt: 0 };
+        await new Email(ENV).reply(msg, { text: "k" });
+        expect(calls[0].body).toMatchObject({ subject: "Re: Hi" });
+    });
+    it("throws a helpful error when not provisioned", async () => {
+        mockFetch(() => ({ json: {} }));
+        await expect(new Email({}).list()).rejects.toThrow(/not provisioned/);
+    });
+    it("surfaces API errors with the server message", async () => {
+        mockFetch(() => ({ status: 403, json: { error: "forbidden", message: "bad token" } }));
+        await expect(new Email(ENV).list()).rejects.toThrow(/bad token/);
+    });
+});

package/dist/hyperliquidBridge.d.ts

@@ -0,0 +1,30 @@
+import type { Chain } from "./chain.js";
+import type { Hex } from "./hex.js";
+export type HlNetwork = "mainnet" | "testnet";
+export interface HlBridgeConfig {
+    /** Arbitrum chainId the deposit transfer goes out on. */
+    chainId: number;
+    /** Hyperliquid bridge (Bridge2) contract — the USDC transfer recipient. */
+    bridge: Hex;
+    /** USDC token on that chain. */
+    usdc: Hex;
+    usdcDecimals: number;
+    /** Hyperliquid enforces a minimum deposit; below it funds are lost. */
+    minUsdc: number;
+}
+export declare const HL_BRIDGE: Record<HlNetwork, HlBridgeConfig>;
+/**
+ * Convert a human USDC amount (e.g. 25 or "25.5") to base units, without float
+ * error. Rejects more fractional digits than the token supports.
+ */
+export declare function usdcBaseUnits(amount: number | string, decimals?: number): bigint;
+export interface DepositOptions {
+    /** "mainnet" (Arbitrum) or "testnet" (Arbitrum Sepolia). Default "mainnet". */
+    network?: HlNetwork;
+}
+/**
+ * Deposit USDC into Hyperliquid from Arbitrum. `chain` must be a Chain on the
+ * matching Arbitrum network with a funded signer. Returns the deposit tx hash;
+ * the credit appears on the signer's Hyperliquid account shortly after.
+ */
+export declare function depositToHyperliquid(chain: Chain, amount: number | string, opts?: DepositOptions): Promise<Hex>;

package/dist/hyperliquidBridge.js

@@ -0,0 +1,61 @@
+// Verify against Hyperliquid docs before relying on the testnet entry; mainnet
+// Bridge2 + native USDC on Arbitrum are the well-known production addresses.
+export const HL_BRIDGE = {
+    mainnet: {
+        chainId: 42161,
+        bridge: "0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7",
+        usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+        usdcDecimals: 6,
+        minUsdc: 5,
+    },
+    testnet: {
+        chainId: 421614,
+        bridge: "0x08cfc1B6b2dCF36A1480b99353A354AA8AC56f89",
+        usdc: "0x1baAbB04529D43a73232B713C0FE471f7c7334d5",
+        usdcDecimals: 6,
+        minUsdc: 5,
+    },
+};
+const ERC20_TRANSFER = [
+    {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+];
+/**
+ * Convert a human USDC amount (e.g. 25 or "25.5") to base units, without float
+ * error. Rejects more fractional digits than the token supports.
+ */
+export function usdcBaseUnits(amount, decimals = 6) {
+    const s = typeof amount === "number" ? amount.toString() : amount.trim();
+    if (!/^\d+(\.\d+)?$/.test(s))
+        throw new Error(`invalid USDC amount: ${amount}`);
+    const [whole, frac = ""] = s.split(".");
+    if (frac.length > decimals)
+        throw new Error(`USDC supports at most ${decimals} decimals`);
+    return BigInt(whole + frac.padEnd(decimals, "0"));
+}
+/**
+ * Deposit USDC into Hyperliquid from Arbitrum. `chain` must be a Chain on the
+ * matching Arbitrum network with a funded signer. Returns the deposit tx hash;
+ * the credit appears on the signer's Hyperliquid account shortly after.
+ */
+export async function depositToHyperliquid(chain, amount, opts = {}) {
+    const cfg = HL_BRIDGE[opts.network ?? "mainnet"];
+    const units = usdcBaseUnits(amount, cfg.usdcDecimals);
+    const min = BigInt(cfg.minUsdc) * 10n ** BigInt(cfg.usdcDecimals);
+    if (units < min)
+        throw new Error(`Hyperliquid minimum deposit is ${cfg.minUsdc} USDC`);
+    return chain.send({
+        address: cfg.usdc,
+        abi: ERC20_TRANSFER,
+        functionName: "transfer",
+        args: [cfg.bridge, units],
+    });
+}

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { Telegram } from "./telegram.js";
 export type { TelegramOptions, BotMessage, SendMessageOptions, ChatJoinRequest } from "./telegram.js";
 export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
 export type { TelegramUser, VerifyOptions } from "./telegramAuth.js";
+export { Email } from "./email.js";
+export type { EmailOptions, EmailMessage, EmailDirection, ListEmailsOptions, SendEmailOptions, SendEmailResult, } from "./email.js";
 export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
 export type { TelegramLink } from "./telegramLinks.js";
 export { tokenBalanceOf, meetsGate } from "./gate.js";
@@ -42,6 +44,8 @@ export { verifyWebhook, signWebhook } from "./webhook.js";
 export type { VerifyWebhookParams, SignatureEncoding } from "./webhook.js";
 export { Hyperliquid } from "./hyperliquid.js";
 export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, PositionInfo, Bbo, } from "./hyperliquid.js";
+export { depositToHyperliquid, usdcBaseUnits, HL_BRIDGE } from "./hyperliquidBridge.js";
+export type { HlNetwork, HlBridgeConfig, DepositOptions } from "./hyperliquidBridge.js";
 export { Polymarket } from "./polymarket.js";
 export type { PolymarketOptions, PolymarketCreds, PlaceOrderParams, Side, OrderType, SignatureType, PriceInterval, PriceHistoryOptions, MarketOutcome, ResolvedMarket, } from "./polymarket.js";
 export { hashTypedData, signTypedData, localAccount } from "./eip712.js";

package/dist/index.js

@@ -28,6 +28,8 @@ export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 // Telegram — webhook verification + reply plumbing for bots.
 export { Telegram } from "./telegram.js";
 export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+// Email — the project's own inbox at {slug}@livo.build (read + send/reply).
+export { Email } from "./email.js";
 export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
 export { tokenBalanceOf, meetsGate } from "./gate.js";
 export { tokenMetadata, ownerOf, tokenURI } from "./reads.js";
@@ -42,6 +44,8 @@ export { verifyWebhook, signWebhook } from "./webhook.js";
 // Hyperliquid — perps/spot data + trading (wraps @nktkas/hyperliquid; signs with
 // the runtime's EIP-712 signer, no viem/ethers in the bundle).
 export { Hyperliquid } from "./hyperliquid.js";
+// Hyperliquid bridge — deposit USDC from Arbitrum into the L1 account (funds-in).
+export { depositToHyperliquid, usdcBaseUnits, HL_BRIDGE } from "./hyperliquidBridge.js";
 // Polymarket — prediction-market data (public, frontend-safe) + CLOB order
 // placement (native EIP-712 + L2 HMAC; no @polymarket/clob-client, no ethers).
 export { Polymarket } from "./polymarket.js";

package/package.json

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