openbroker 1.3.1 → 1.4.0

package/dist/auto/types.d.ts

@@ -0,0 +1,236 @@
+import type { HyperliquidClient } from '../core/client.js';
+/** What an automation .ts file exports */
+export type AutomationFactory = (api: AutomationAPI) => void | Promise<void>;
+/** Config field descriptor for example automations */
+export interface AutomationConfigField {
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    default: unknown;
+    required?: boolean;
+}
+/** Config metadata exported by example automations as `export const config` */
+export interface AutomationConfig {
+    description: string;
+    fields: Record<string, AutomationConfigField>;
+}
+export type AutomationEventType = 'tick' | 'price_change' | 'funding_update' | 'position_opened' | 'position_closed' | 'position_changed' | 'pnl_threshold' | 'margin_warning' | 'order_filled' | 'order_update' | 'liquidation';
+export interface AutomationEventPayloads {
+    tick: {
+        timestamp: number;
+        pollCount: number;
+    };
+    price_change: {
+        coin: string;
+        oldPrice: number;
+        newPrice: number;
+        changePct: number;
+    };
+    funding_update: {
+        coin: string;
+        fundingRate: number;
+        annualized: number;
+        premium: number;
+    };
+    position_opened: {
+        coin: string;
+        side: 'long' | 'short';
+        size: number;
+        entryPrice: number;
+    };
+    position_closed: {
+        coin: string;
+        previousSize: number;
+        entryPrice: number;
+    };
+    position_changed: {
+        coin: string;
+        oldSize: number;
+        newSize: number;
+        entryPrice: number;
+    };
+    pnl_threshold: {
+        coin: string;
+        unrealizedPnl: number;
+        changePct: number;
+        positionValue: number;
+    };
+    margin_warning: {
+        marginUsedPct: number;
+        equity: number;
+        marginUsed: number;
+    };
+    /**
+     * Fires on every trade fill — partial and terminal — sourced from the
+     * Hyperliquid `userFills` WS stream. `size` is the fill delta (NOT remaining
+     * size of the order). `fee` and `closedPnl` are in USD (converted from the
+     * raw fee denomination using `price` when `feeToken !== "USDC"`, which
+     * happens on spot buys where the fee is charged in the received asset).
+     * `feeToken` is the original denomination so consumers can identify legs
+     * that won't carry a builder fee (Hyperliquid only charges builder fees on
+     * USDC-denominated trades). `crossed` is true when this side was the taker.
+     * Fee/pnl/crossed/feeToken are optional so older consumers that only read
+     * coin/oid/side/size/price keep working.
+     */
+    order_filled: {
+        coin: string;
+        oid: number;
+        side: 'buy' | 'sell';
+        size: number;
+        price: number;
+        fee?: number;
+        feeToken?: string;
+        closedPnl?: number;
+        crossed?: boolean;
+    };
+    /** Real-time order lifecycle event via WebSocket (filled, canceled, rejected, triggered, etc.) */
+    order_update: {
+        coin: string;
+        oid: number;
+        side: 'buy' | 'sell';
+        size: number;
+        price: number;
+        origSize: number;
+        status: string;
+        statusTimestamp: number;
+    };
+    /** Liquidation event via WebSocket — only source for liquidation alerts */
+    liquidation: {
+        lid: number;
+        liquidator: string;
+        liquidatedUser: string;
+        liquidatedNtlPos: number;
+        liquidatedAccountValue: number;
+    };
+}
+export type AutomationEventHandler<E extends AutomationEventType> = (payload: AutomationEventPayloads[E]) => void | Promise<void>;
+export interface AutomationState {
+    get<T = unknown>(key: string, defaultValue?: T): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export interface AutomationLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+export interface AutomationAudit {
+    /** Record a custom audit note for later reporting. */
+    record(kind: string, payload?: unknown): void;
+    /** Record a numeric metric with optional dimensions/tags. */
+    metric(name: string, value: number, tags?: Record<string, unknown>): void;
+}
+/**
+ * Hook for external monitoring packages (e.g. `openbroker-monitoring`) to
+ * receive audit events. The runtime fans out every note, metric, and
+ * audited write-method call to every observer it has loaded.
+ *
+ * Observers are auto-loaded via convention dynamic-import — the runtime
+ * tries `await import('openbroker-monitoring')` at startup and uses the
+ * default export (a factory returning an observer or null).
+ */
+export interface AutomationAuditObserver {
+    onNote?(kind: string, payload?: unknown): void;
+    onMetric?(name: string, value: number, tags?: Record<string, unknown>): void;
+    onAgentAction?(action: string, status: 'success' | 'error', details: Record<string, unknown>, txHash?: string): void;
+}
+export interface PublishOptions {
+    /** Human-readable name for the hook (appears in logs). Default: "ob-auto-<id>" */
+    name?: string;
+    /** Wake mode: "now" triggers immediate agent turn, "next-heartbeat" queues. Default: "now" */
+    wakeMode?: 'now' | 'next-heartbeat';
+    /** Whether to deliver the agent response to messaging channels. Default: true */
+    deliver?: boolean;
+    /** Target channel (e.g. "slack", "telegram", "last"). Default: agent decides */
+    channel?: string;
+}
+export interface AutomationAPI {
+    /** Full Hyperliquid client (42+ methods) */
+    client: HyperliquidClient;
+    /** Convenience utilities from core */
+    utils: {
+        roundPrice: (price: number, szDecimals: number, isSpot?: boolean) => string;
+        roundSize: (size: number, szDecimals: number) => string;
+        sleep: (ms: number) => Promise<void>;
+        normalizeCoin: (coin: string) => string;
+        formatUsd: (amount: number | string) => string;
+        formatPercent: (value: number | string, decimals?: number) => string;
+        annualizeFundingRate: (hourlyRate: number | string) => number;
+    };
+    /** Subscribe to a market/account event */
+    on<E extends AutomationEventType>(event: E, handler: AutomationEventHandler<E>): void;
+    /** Run a handler on a recurring interval (ms). Aligned to the poll loop. */
+    every(intervalMs: number, handler: () => void | Promise<void>): void;
+    /** Called after all handlers are registered and polling begins */
+    onStart(handler: () => void | Promise<void>): void;
+    /** Called when automation is stopping (SIGINT, manual stop). Use for cleanup. */
+    onStop(handler: () => void | Promise<void>): void;
+    /** Called when a handler throws. The error is already logged — use this for recovery logic. */
+    onError(handler: (error: Error) => void | Promise<void>): void;
+    /**
+     * Publish a message to the OpenClaw agent via webhook.
+     * Sends to POST /hooks/agent on the local gateway, triggering an agent turn.
+     * The agent receives the message and can act on it (notify user, trade, etc.).
+     *
+     * @param message — The message string the agent will receive
+     * @param options — Optional: name, wakeMode, deliver, channel
+     * @returns true if delivered, false if webhook is not configured
+     */
+    publish(message: string, options?: PublishOptions): Promise<boolean>;
+    /** Persisted key-value state (~/.openbroker/state/<id>.json) */
+    state: AutomationState;
+    /** Structured logger */
+    log: AutomationLogger;
+    /** Local audit trail persisted to ~/.openbroker/automation-audit.sqlite */
+    audit: AutomationAudit;
+    /** Unique automation ID (derived from filename or --id flag) */
+    id: string;
+    /** True if running in --dry mode (write methods are intercepted) */
+    dryRun: boolean;
+}
+export interface AutomationSnapshot {
+    prices: Map<string, number>;
+    positions: Map<string, PositionSnapshot>;
+    openOrderIds: Set<number>;
+    equity: number;
+    marginUsed: number;
+    marginUsedPct: number;
+    fundingRates: Map<string, {
+        rate: number;
+        premium: number;
+    }>;
+    timestamp: number;
+}
+export interface PositionSnapshot {
+    coin: string;
+    size: number;
+    entryPrice: number;
+    positionValue: number;
+    unrealizedPnl: number;
+    liquidationPx: number | null;
+    leverage: number;
+    marginUsed: number;
+}
+export interface ScheduledTask {
+    intervalMs: number;
+    handler: () => void | Promise<void>;
+    lastRun: number;
+}
+export interface RunningAutomation {
+    id: string;
+    scriptPath: string;
+    startedAt: Date;
+    pollCount: number;
+    eventsEmitted: number;
+    dryRun: boolean;
+    /**
+     * Stop the automation.
+     * @param opts.persist If false, keep the entry in the file registry so it
+     *   restarts when the gateway comes back up. Default: true (fully remove).
+     */
+    stop: (opts?: {
+        persist?: boolean;
+    }) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auto/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../scripts/auto/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7E,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CAC/C;AAID,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,cAAc,GACd,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACtF,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3F,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5F,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACjG,cAAc,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E;;;;;;;;;;;OAWG;IACH,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,kGAAkG;IAClG,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,2EAA2E;IAC3E,WAAW,EAAE;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,mBAAmB,IAC9D,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIhE,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC/D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,6DAA6D;IAC7D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3E;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7E,aAAa,CAAC,CACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,GAAG,OAAO,EAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAAC;CACT;AAID,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,GAAG,gBAAgB,CAAC;IACpC,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,MAAM,EAAE,iBAAiB,CAAC;IAE1B,sCAAsC;IACtC,KAAK,EAAE;QACL,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;QAC5E,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;QACxD,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QACrC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;QACxC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM,CAAC;QAC/C,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QACrE,oBAAoB,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM,CAAC;KAC/D,CAAC;IAEF,0CAA0C;IAC1C,EAAE,CAAC,CAAC,SAAS,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEtF,4EAA4E;IAC5E,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAErE,kEAAkE;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnD,iFAAiF;IACjF,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElD,+FAA+F;IAC/F,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE/D;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErE,gEAAgE;IAChE,KAAK,EAAE,eAAe,CAAC;IAEvB,wBAAwB;IACxB,GAAG,EAAE,gBAAgB,CAAC;IAEtB,2EAA2E;IAC3E,KAAK,EAAE,eAAe,CAAC;IAEvB,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IAEX,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD"}

package/dist/auto/types.js

@@ -0,0 +1,3 @@
+// Trading Automation Harness — Type definitions
+// The API contract that automation scripts code against
+export {};