@jango-blockchained/hoox-shared 1.0.8

package/README.md

@@ -0,0 +1,27 @@
+# @hoox/shared
+
+Shared types, custom router with path parameter support (`:param` syntax), middleware (auth, CORS, rate-limit, logger), error factories (`Errors.*`), generic exchange provider factory (`ExchangeRouter`, `IExchangeProvider`), and utilities.
+
+## For CLI Users
+
+This is an internal package — installed automatically as a workspace dependency. No CLI commands needed.
+
+→ [Architecture Overview](../../docs/devops/architecture/overview.md)
+
+## For Operators
+
+This package provides the shared foundation for all Hoox workers. It includes:
+
+- **Custom Router** — Lightweight routing with exact-match fast path and `:param` path parameter support. Handlers receive extracted params as an optional 4th argument.
+- **Error Factories** — `Errors.*` helpers (`badRequest`, `unauthorized`, `forbidden`, `notFound`, `internal`, etc.) for consistent JSON error responses across all workers.
+- **Exchange Provider Factory** — Generic `ExchangeRouter<TClient, TEnv>` and `IExchangeProvider<TClient, TEnv>` for registering and resolving exchange clients by name.
+- **Middleware** — Logger (`createLogger`, `withRequestLog`), auth (`requireInternalAuth`), CORS, rate limiting, and Zod validation.
+- **Utilities** — `toError`, `serviceFetch`, `createJsonResponse`, KV helpers, health check, analytics tracking.
+
+→ [Architecture Overview](../../docs/devops/architecture/overview.md)
+
+## Development
+
+```bash
+bun test packages/shared
+```

package/dist/analytics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Analytics tracking utilities for Cloudflare Workers
+ * Centralizes the trackAnalytics helper used across all workers
+ */
+/**
+ * Environment with optional analytics service binding.
+ * Workers that support analytics tracking should extend this type.
+ */
+export interface AnalyticsEnv {
+    ANALYTICS_SERVICE?: Fetcher;
+    [key: string]: unknown;
+}
+/**
+ * Track an analytics event by forwarding to the analytics worker.
+ * Non-blocking: failures are logged but never throw.
+ *
+ * @param env - Worker environment with optional ANALYTICS_SERVICE binding
+ * @param endpoint - Analytics endpoint path (e.g., "/track/api-call")
+ * @param body - JSON-serializable payload to send
+ */
+export declare function trackAnalytics(env: AnalyticsEnv, endpoint: string, body: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/analytics.js

@@ -0,0 +1,34 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/analytics.ts
+async function trackAnalytics(env, endpoint, body) {
+  if (!env.ANALYTICS_SERVICE)
+    return;
+  try {
+    await env.ANALYTICS_SERVICE.fetch(new Request(`http://localhost${endpoint}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    }));
+  } catch (e) {
+    console.error("Analytics tracking failed:", e);
+  }
+}
+export {
+  trackAnalytics
+};

package/dist/api-client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * API Client — Bun fetch wrapper with AbortController timeouts, retry logic,
+ * and connection-aware error handling for the Hoox TUI dashboard.
+ *
+ * All fetch calls include a 5s timeout via AbortController.
+ * Network errors (fetch failures, timeouts) are retried with exponential backoff.
+ * HTTP 401/403 errors are NOT retried — they indicate auth/config issues.
+ * HTTP 429 (rate limit) triggers a backing-off warning.
+ */
+export declare class WorkerAPIError extends Error {
+    status: number;
+    retryable: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        retryable?: boolean;
+    });
+}
+/**
+ * Perform an API fetch with timeout, retry logic, and error handling.
+ *
+ * Retry behavior:
+ * - Network errors (connection refused, DNS, timeout): up to MAX_RETRIES,
+ *   with exponential backoff: 1s → 2s → 4s → ... capped at 16s.
+ * - HTTP 401/403: NO retry — fail immediately.
+ * - HTTP 429 (rate limited): NO retry — fail with rate limit info.
+ * - HTTP 5xx: retry once.
+ *
+ * @param path    API path (e.g. "/workers")
+ * @param options Fetch options (merged with auth header and timeout signal)
+ * @returns       Parsed JSON response body
+ */
+export declare function hooxFetch<T = unknown>(path: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,qBAAa,cAAe,SAAQ,KAAK;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;gBAGjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;CAOtE;AAyCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,CAAC,CAAC,CA8FZ"}

package/dist/api-client.js

@@ -0,0 +1,124 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/api-client.ts
+var exports_api_client = {};
+__export(exports_api_client, {
+  hooxFetch: () => hooxFetch,
+  WorkerAPIError: () => WorkerAPIError
+});
+function isRetryableStatus(status) {
+  if (status === 401 || status === 403 || status === 429)
+    return false;
+  if (status >= 500)
+    return true;
+  if (status === 408)
+    return true;
+  return false;
+}
+function isNetworkError(error) {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return error.name === "AbortError" || error.name === "TimeoutError" || msg.includes("fetch") || msg.includes("network") || msg.includes("econnrefused") || msg.includes("enotfound") || msg.includes("dns") || msg.includes("timeout");
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function hooxFetch(path, options) {
+  let lastError;
+  for (let attempt = 0;attempt <= MAX_RETRIES; attempt++) {
+    const controller = new AbortController;
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const url = `${API_BASE}${path}`;
+      const headers = {
+        "Content-Type": "application/json",
+        ...API_TOKEN ? { Authorization: `Bearer ${API_TOKEN}` } : {},
+        ...options?.headers
+      };
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+      if (response.status === 429) {
+        throw new WorkerAPIError("API rate limited \u2014 backing off", {
+          status: 429,
+          retryable: false
+        });
+      }
+      if (response.status === 401 || response.status === 403) {
+        throw new WorkerAPIError(`Authentication failed (HTTP ${response.status})`, { status: response.status, retryable: false });
+      }
+      if (!response.ok) {
+        if (attempt < MAX_RETRIES && isRetryableStatus(response.status)) {
+          const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+          await sleep(delay);
+          continue;
+        }
+        throw new WorkerAPIError(`HTTP ${response.status}: ${response.statusText}`, {
+          status: response.status,
+          retryable: isRetryableStatus(response.status)
+        });
+      }
+      return await response.json();
+    } catch (error) {
+      lastError = error;
+      if (error instanceof WorkerAPIError && !error.retryable) {
+        throw error;
+      }
+      if (attempt < MAX_RETRIES && isNetworkError(error)) {
+        const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+        await sleep(delay);
+        continue;
+      }
+      if (!(error instanceof WorkerAPIError)) {
+        throw new WorkerAPIError(`Network request failed: ${error.message}`, { cause: error, retryable: false, status: 0 });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  throw new WorkerAPIError("Max retries exhausted", {
+    cause: lastError,
+    retryable: false
+  });
+}
+var API_BASE, API_TOKEN, FETCH_TIMEOUT_MS = 5000, MAX_RETRIES = 3, BASE_RETRY_DELAY_MS = 1000, MAX_RETRY_DELAY_MS = 16000, WorkerAPIError;
+var init_api_client = __esm(() => {
+  API_BASE = process.env.HOOX_API_URL || "http://localhost:8787";
+  API_TOKEN = process.env.HOOX_API_TOKEN || "";
+  WorkerAPIError = class WorkerAPIError extends Error {
+    status;
+    retryable;
+    constructor(message, options) {
+      super(message, { cause: options?.cause });
+      this.name = "WorkerAPIError";
+      this.status = options?.status ?? 0;
+      this.retryable = options?.retryable ?? false;
+    }
+  };
+});
+init_api_client();
+
+export {
+  hooxFetch,
+  WorkerAPIError
+};

package/dist/colors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Color Tokens — Maps hoox landing page design system to terminal-safe RGBA hex values.
+ *
+ * Design DNA:
+ *   - Dark monochrome background: oklch(0.08 0 0) → #0D1117
+ *   - Orange accent: oklch(0.7 0.2 45) → #E8780A
+ *   - Squared edges (no rounding — editorial aesthetic)
+ *
+ * Usage: import { Colors } from "@hoox/shared"
+ *        <text fg={Colors.accent}>Important</text>
+ */
+export declare const Colors: {
+    readonly background: "#0D1117";
+    readonly foreground: "#EEEEEE";
+    readonly card: "#1C1C1F";
+    readonly border: "#484848";
+    readonly muted: "#A0A0A0";
+    readonly "muted-foreground": "#6E6E6E";
+    readonly dim: "#3B3B3D";
+    readonly accent: "#E8780A";
+    readonly "accent-dim": "#B85E08";
+    readonly success: "#00FF88";
+    readonly warning: "#FFAA00";
+    readonly error: "#FF4444";
+    readonly info: "#4488FF";
+    readonly text: "#EEEEEE";
+    readonly "text-muted": "#A0A0A0";
+    readonly "text-dim": "#6E6E6E";
+    readonly panel: "#1C1C1F";
+    readonly divider: "#484848";
+    readonly highlight: "#E8780A";
+};
+export type ColorKey = keyof typeof Colors;
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;CA2BT,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,MAAM,CAAC"}

package/dist/colors.js

@@ -0,0 +1,42 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/colors.ts
+var Colors = {
+  background: "#0D1117",
+  foreground: "#EEEEEE",
+  card: "#1C1C1F",
+  border: "#484848",
+  muted: "#A0A0A0",
+  "muted-foreground": "#6E6E6E",
+  dim: "#3B3B3D",
+  accent: "#E8780A",
+  "accent-dim": "#B85E08",
+  success: "#00FF88",
+  warning: "#FFAA00",
+  error: "#FF4444",
+  info: "#4488FF",
+  text: "#EEEEEE",
+  "text-muted": "#A0A0A0",
+  "text-dim": "#6E6E6E",
+  panel: "#1C1C1F",
+  divider: "#484848",
+  highlight: "#E8780A"
+};
+export {
+  Colors
+};

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface HooxConfig {
+    apiUrl: string;
+    apiToken: string;
+    refreshIntervalMs: number;
+    theme: "dark" | "light";
+    activeExchanges: string[];
+    notifications: {
+        alerts: boolean;
+        trades: boolean;
+        debug: boolean;
+        system: boolean;
+    };
+    soundEnabled: boolean;
+    defaultView: string;
+}
+/** Read config from disk, merging with defaults and env vars */
+export declare function readConfigSync(): HooxConfig;
+export declare function readConfig(): Promise<HooxConfig>;
+/** Write config to disk */
+export declare function writeConfigSync(config: HooxConfig): void;
+export declare function writeConfig(config: HooxConfig): Promise<void>;
+/** Validate config — returns array of error messages */
+export declare function validateConfig(config: Partial<HooxConfig>): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE;QACb,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAkBD,gEAAgE;AAChE,wBAAgB,cAAc,IAAI,UAAU,CAsB3C;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAEtD;AAED,2BAA2B;AAC3B,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CASxD;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,EAAE,CAepE"}

package/dist/config.js

@@ -0,0 +1,91 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/config.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var HOX_DIR = join(homedir(), ".hoox");
+var CONFIG_PATH = join(HOX_DIR, "config.json");
+var DEFAULT_CONFIG = {
+  apiUrl: "http://localhost:8787",
+  apiToken: "",
+  refreshIntervalMs: 500,
+  theme: "dark",
+  activeExchanges: ["binance", "bybit", "mexc"],
+  notifications: {
+    alerts: true,
+    trades: true,
+    debug: false,
+    system: true
+  },
+  soundEnabled: true,
+  defaultView: "dashboard"
+};
+function readConfigSync() {
+  const envConfig = {
+    apiUrl: process.env.HOOX_API_URL,
+    apiToken: process.env.HOOX_API_TOKEN
+  };
+  let fileConfig = {};
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      fileConfig = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+  } catch {}
+  return {
+    ...DEFAULT_CONFIG,
+    ...fileConfig,
+    ...Object.fromEntries(Object.entries(envConfig).filter(([_, v]) => v !== undefined))
+  };
+}
+async function readConfig() {
+  return readConfigSync();
+}
+function writeConfigSync(config) {
+  try {
+    if (!existsSync(HOX_DIR)) {
+      mkdirSync(HOX_DIR, { recursive: true });
+    }
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+  } catch (err) {
+    console.error("Failed to write config:", err);
+  }
+}
+async function writeConfig(config) {
+  writeConfigSync(config);
+}
+function validateConfig(config) {
+  const errors = [];
+  if (config.apiUrl && !config.apiUrl.startsWith("http")) {
+    errors.push("apiUrl must start with http:// or https://");
+  }
+  if (config.refreshIntervalMs !== undefined && config.refreshIntervalMs < 100) {
+    errors.push("refreshIntervalMs must be >= 100ms");
+  }
+  if (config.theme && !["dark", "light"].includes(config.theme)) {
+    errors.push('theme must be "dark" or "light"');
+  }
+  return errors;
+}
+export {
+  writeConfigSync,
+  writeConfig,
+  validateConfig,
+  readConfigSync,
+  readConfig
+};

package/dist/d1/index.d.ts

@@ -0,0 +1,5 @@
+export { D1Repository } from "./repository";
+export type { BatchStatement } from "./repository";
+export type { TradeRecord, PositionRecord, BalanceRecord, SystemLogRecord, TradeSignalRecord, D1QueryResult, } from "./schemas";
+export { TradeRecordSchema, PositionRecordSchema, BalanceRecordSchema, SystemLogRecordSchema, TradeSignalRecordSchema, } from "./schemas";
+//# sourceMappingURL=index.d.ts.map

package/dist/d1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/d1/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,WAAW,CAAC"}