@hoox-sh/hoox-shared 1.2.0

package/README.md

@@ -0,0 +1,44 @@
+# @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)
+
+## Public API
+
+This package is published as `@hoox-sh/hoox-shared` and exposes a layered import surface via the package `exports` map. All subpaths resolve to compiled `dist/*.js` and `dist/*.d.ts` files — the package tarball does **not** include TypeScript sources.
+
+| Import                                 | Resolves to               | Notes                                                               |
+| -------------------------------------- | ------------------------- | ------------------------------------------------------------------- |
+| `@hoox-sh/hoox-shared`                 | `dist/index.js`           | Main barrel — everything in `src/index.ts`                          |
+| `@hoox-sh/hoox-shared/<subdir>`        | `dist/<subdir>/index.js`  | Sub-barrel for the named subdirectory                               |
+| `@hoox-sh/hoox-shared/<subdir>/<file>` | `dist/<subdir>/<file>.js` | Specific submodule file                                             |
+| `@hoox-sh/hoox-shared/stores/<store>`  | `dist/stores/<store>.js`  | Zustand stores — deep-import only (no barrel)                       |
+| `@hoox-sh/hoox-shared/types`           | `dist/types/index.d.ts`   | Type-only re-exports                                                |
+| `@hoox-sh/hoox-shared/<anything-else>` | `dist/<anything-else>.js` | Catch-all for top-level modules (e.g. `errors`, `router`, `kvKeys`) |
+
+The named subdirectories with deep-import support are: `middleware`, `d1`, `schemas`, `wizard`, `exchanges`. Each one re-exports its submodules from its `index.ts` barrel, so the bare-subdir form (`<subdir>`) and the deep form (`<subdir>/<file>`) return the same symbols — the bare form is just the pre-bundled rollup.
+
+**Recommendation:** prefer the bare form for subdirectories (`hoox-shared/middleware`) unless you specifically need a single submodule to keep the import graph small. The bare form gives you a stable, curated surface; the deep form is for tree-shaking-conscious or very specific use cases.
+
+## Development
+
+```bash
+bun test packages/shared
+```

package/dist/agent-config-fields.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** CONFIG_KV key for the agent JSON config document. */
+export declare const AGENT_CONFIG_KV_KEY = "agent:config";
+export type AgentConfigFieldSpec = {
+    kind: "top";
+    key: "defaultProvider" | "fallbackChain" | "timeoutMs" | "retryCount" | "maxDailyDrawdownPercent" | "trailingStopPercent" | "takeProfitPercent";
+} | {
+    kind: "model";
+    provider: string;
+};
+/**
+ * Composite field keys (`section:field` from dashboard.jsonc) that embed
+ * into agent:config rather than flat CONFIG_KV keys.
+ */
+export declare const AGENT_CONFIG_EMBEDDED_FIELDS: Readonly<Record<string, AgentConfigFieldSpec>>;
+/** Sections whose fields are edited via agent:config (not flat KV). */
+export declare const DASHBOARD_SECTIONS_AGENT_CONFIG: ReadonlySet<string>;
+export declare function isAgentConfigEmbeddedField(fieldKey: string): boolean;
+export declare function isAgentConfigSection(sectionId: string): boolean;
+/** Parse agent:config KV payload (handles double-encoded JSON strings). */
+export declare function parseAgentConfigJson(raw: string | null | undefined): Record<string, unknown>;
+export declare function serializeAgentConfigForKv(config: Record<string, unknown>): string;
+export declare function getAgentConfigEmbeddedValue(config: Record<string, unknown>, fieldKey: string): string | number | boolean | undefined;
+export declare function setAgentConfigEmbeddedValue(config: Record<string, unknown>, fieldKey: string, value: string | number | boolean): Record<string, unknown>;
+/** Expand agent:config into dashboard composite field keys for UI forms. */
+export declare function expandAgentConfigToFieldMap(config: Record<string, unknown>): Record<string, string | number | boolean>;
+/** Apply multiple embedded field updates onto an agent:config object. */
+export declare function applyAgentConfigFieldUpdates(config: Record<string, unknown>, updates: Record<string, string | number | boolean>): Record<string, unknown>;
+//# sourceMappingURL=agent-config-fields.d.ts.map

package/dist/agent-config-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-fields.d.ts","sourceRoot":"","sources":["../src/agent-config-fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,iBAAkB,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EACC,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,YAAY,GACZ,yBAAyB,GACzB,qBAAqB,GACrB,mBAAmB,CAAC;CACzB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CACjD,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAiBrC,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAG9D,CAAC;AAEH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAER;AAUD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CA+BvC;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsCzB;AAED,4EAA4E;AAC5E,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAO3C;AAED,yEAAyE;AACzE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB"}

package/dist/agent-config-fields.js

@@ -0,0 +1,220 @@
+// @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/kvKeys.ts
+var KV_TRADE_DEFAULT_LEVERAGE = "trade:default_leverage";
+var KV_TRADE_MAX_POSITION_SIZE = "trade:max_position_size";
+var KV_TRADE_MAX_DAILY_DRAWDOWN_PERCENT = "trade:max_daily_drawdown_percent";
+var KV_TRADE_TRAILING_STOP_PERCENT = "trade:trailing_stop_percent";
+var KV_TRADE_KILL_SWITCH = "trade:kill_switch";
+var KV_TRADE_ROUTING = "trade:routing";
+var KV_BOT_ENABLED = "bot:enabled";
+var KV_BOT_DEFAULT_CHAT_ID = "bot:default_chat_id";
+var KV_BOT_NOTIFY_ON_EXECUTION = "bot:notify_on_execution";
+var KV_BOT_NOTIFY_ON_ERROR = "bot:notify_on_error";
+var KV_WEBHOOK_IP_CHECK_ENABLED = "webhook:tradingview:ip_check_enabled";
+var KV_WEBHOOK_ALLOWED_IPS = "webhook:tradingview:allowed_ips";
+var KV_WEBHOOK_QUEUE_MODE = "webhook:queue_mode";
+var KV_EMAIL_SCAN_SUBJECT = "email:scan_subject";
+var KV_EMAIL_USE_IMAP = "email:use_imap";
+var KV_EMAIL_COIN_PATTERN = "email:coin_pattern";
+var KV_EMAIL_ACTION_PATTERN = "email:action_pattern";
+var KV_EMAIL_QUANTITY_MULTIPLIER = "email:quantity_multiplier";
+var KV_AGENT_CONFIG = "agent:config";
+var KV_AGENT_OPENAI_KEY = "agent:openai_key";
+var KV_AGENT_ANTHROPIC_KEY = "agent:anthropic_key";
+var KV_AGENT_GOOGLE_KEY = "agent:google_key";
+var KV_DASHBOARD_AI_HEALTH_SUMMARY = "dashboard:ai_health_summary";
+var KV_HEALTH_CHECK = "health_check";
+var KV_HOUSEKEEPING_LAST_CHECK = "housekeeping:last_check";
+var QUEUE_MODE_FAILOVER = "queue_failover";
+var QUEUE_MODE_EVERYWHERE = "queue_everywhere";
+var QUEUE_MODE_DISABLED = "queue_disabled";
+var KVKeys = {
+  KV_TRADE_DEFAULT_LEVERAGE,
+  KV_TRADE_MAX_POSITION_SIZE,
+  KV_TRADE_MAX_DAILY_DRAWDOWN_PERCENT,
+  KV_TRADE_TRAILING_STOP_PERCENT,
+  KV_TRADE_KILL_SWITCH,
+  KV_TRADE_ROUTING,
+  KV_BOT_ENABLED,
+  KV_BOT_DEFAULT_CHAT_ID,
+  KV_BOT_NOTIFY_ON_EXECUTION,
+  KV_BOT_NOTIFY_ON_ERROR,
+  KV_WEBHOOK_IP_CHECK_ENABLED,
+  KV_WEBHOOK_ALLOWED_IPS,
+  KV_WEBHOOK_QUEUE_MODE,
+  KV_EMAIL_SCAN_SUBJECT,
+  KV_EMAIL_USE_IMAP,
+  KV_EMAIL_COIN_PATTERN,
+  KV_EMAIL_ACTION_PATTERN,
+  KV_EMAIL_QUANTITY_MULTIPLIER,
+  KV_AGENT_CONFIG,
+  KV_AGENT_OPENAI_KEY,
+  KV_AGENT_ANTHROPIC_KEY,
+  KV_AGENT_GOOGLE_KEY,
+  KV_DASHBOARD_AI_HEALTH_SUMMARY,
+  KV_HEALTH_CHECK,
+  KV_HOUSEKEEPING_LAST_CHECK,
+  QUEUE_MODE_FAILOVER,
+  QUEUE_MODE_EVERYWHERE,
+  QUEUE_MODE_DISABLED
+};
+
+// src/agent-config-fields.ts
+var AGENT_CONFIG_KV_KEY = KV_AGENT_CONFIG;
+var AGENT_CONFIG_EMBEDDED_FIELDS = {
+  "providers:default_provider": { kind: "top", key: "defaultProvider" },
+  "providers:fallback_chain": { kind: "top", key: "fallbackChain" },
+  "providers:timeout_ms": { kind: "top", key: "timeoutMs" },
+  "providers:retry_count": { kind: "top", key: "retryCount" },
+  "models:workers_ai_model": { kind: "model", provider: "workers-ai" },
+  "models:openai_model": { kind: "model", provider: "openai" },
+  "models:anthropic_model": { kind: "model", provider: "anthropic" },
+  "models:google_model": { kind: "model", provider: "google" },
+  "risk:max_daily_drawdown_percent": {
+    kind: "top",
+    key: "maxDailyDrawdownPercent"
+  },
+  "risk:trailing_stop_percent": { kind: "top", key: "trailingStopPercent" },
+  "risk:take_profit_percent": { kind: "top", key: "takeProfitPercent" }
+};
+var DASHBOARD_SECTIONS_AGENT_CONFIG = new Set([
+  "providers",
+  "models"
+]);
+function isAgentConfigEmbeddedField(fieldKey) {
+  return Object.prototype.hasOwnProperty.call(AGENT_CONFIG_EMBEDDED_FIELDS, fieldKey);
+}
+function isAgentConfigSection(sectionId) {
+  return DASHBOARD_SECTIONS_AGENT_CONFIG.has(sectionId);
+}
+function parseAgentConfigJson(raw) {
+  if (raw === null || raw === undefined || raw === "")
+    return {};
+  try {
+    let v = JSON.parse(raw);
+    if (typeof v === "string") {
+      try {
+        v = JSON.parse(v);
+      } catch {
+        return {};
+      }
+    }
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      return { ...v };
+    }
+  } catch {}
+  return {};
+}
+function serializeAgentConfigForKv(config) {
+  return JSON.stringify(config);
+}
+var NUMBER_TOP_KEYS = new Set([
+  "timeoutMs",
+  "retryCount",
+  "maxDailyDrawdownPercent",
+  "trailingStopPercent",
+  "takeProfitPercent"
+]);
+function getAgentConfigEmbeddedValue(config, fieldKey) {
+  const spec = AGENT_CONFIG_EMBEDDED_FIELDS[fieldKey];
+  if (!spec)
+    return;
+  if (spec.kind === "model") {
+    const map = config.modelMap;
+    if (!map || typeof map !== "object" || Array.isArray(map))
+      return;
+    const v2 = map[spec.provider];
+    if (typeof v2 === "string" || typeof v2 === "number" || typeof v2 === "boolean")
+      return v2;
+    return;
+  }
+  const v = config[spec.key];
+  if (spec.key === "fallbackChain") {
+    if (Array.isArray(v))
+      return JSON.stringify(v);
+    if (typeof v === "string")
+      return v;
+    return;
+  }
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+    return v;
+  }
+  return;
+}
+function setAgentConfigEmbeddedValue(config, fieldKey, value) {
+  const spec = AGENT_CONFIG_EMBEDDED_FIELDS[fieldKey];
+  if (!spec)
+    return { ...config };
+  const next = { ...config };
+  if (spec.kind === "model") {
+    const prev = next.modelMap && typeof next.modelMap === "object" && !Array.isArray(next.modelMap) ? next.modelMap : {};
+    next.modelMap = { ...prev, [spec.provider]: String(value) };
+    return next;
+  }
+  if (spec.key === "fallbackChain") {
+    if (typeof value === "string") {
+      try {
+        next.fallbackChain = JSON.parse(value);
+      } catch {
+        next.fallbackChain = value;
+      }
+    } else {
+      next.fallbackChain = value;
+    }
+    return next;
+  }
+  if (NUMBER_TOP_KEYS.has(spec.key)) {
+    const n = typeof value === "number" ? value : Number(value);
+    next[spec.key] = Number.isFinite(n) ? n : value;
+    return next;
+  }
+  next[spec.key] = value;
+  return next;
+}
+function expandAgentConfigToFieldMap(config) {
+  const out = {};
+  for (const fieldKey of Object.keys(AGENT_CONFIG_EMBEDDED_FIELDS)) {
+    const v = getAgentConfigEmbeddedValue(config, fieldKey);
+    if (v !== undefined)
+      out[fieldKey] = v;
+  }
+  return out;
+}
+function applyAgentConfigFieldUpdates(config, updates) {
+  let next = { ...config };
+  for (const [fieldKey, value] of Object.entries(updates)) {
+    if (isAgentConfigEmbeddedField(fieldKey)) {
+      next = setAgentConfigEmbeddedValue(next, fieldKey, value);
+    }
+  }
+  return next;
+}
+export {
+  setAgentConfigEmbeddedValue,
+  serializeAgentConfigForKv,
+  parseAgentConfigJson,
+  isAgentConfigSection,
+  isAgentConfigEmbeddedField,
+  getAgentConfigEmbeddedValue,
+  expandAgentConfigToFieldMap,
+  applyAgentConfigFieldUpdates,
+  DASHBOARD_SECTIONS_AGENT_CONFIG,
+  AGENT_CONFIG_KV_KEY,
+  AGENT_CONFIG_EMBEDDED_FIELDS
+};

package/dist/analytics.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * 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.
+ *
+ * Note on auth: `trackAnalytics` reads `INTERNAL_KEY_BINDING` from the
+ * passed env to authenticate with the analytics worker (its `/track/*`
+ * routes are gated by `requireInternalAuth`). We don't declare the
+ * property here because Cloudflare's generated `Env` type already
+ * includes it as a required string, and declaring it again as
+ * `INTERNAL_KEY_BINDING?: string` would conflict with workers that
+ * `extends Cloudflare.Env, AnalyticsEnv` (TS2320). The property is
+ * accessed dynamically; production envs from wrangler always have it,
+ * and test mocks add it explicitly via spread.
+ */
+export interface AnalyticsEnv {
+    ANALYTICS_SERVICE?: Fetcher;
+}
+/**
+ * Optional configuration for trackAnalytics.
+ */
+export interface TrackAnalyticsOptions {
+    /**
+     * Custom indexes to attach to the Analytics Engine data point.
+     * Use this to tag rows with stable identifiers (e.g. probe_id)
+     * so they can be SQL-queried later.
+     */
+    indexes?: readonly string[];
+}
+/**
+ * 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
+ * @param options - Optional config (currently supports `indexes`)
+ */
+export declare function trackAnalytics(env: AnalyticsEnv, endpoint: string, body: Record<string, unknown>, options?: TrackAnalyticsOptions): 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;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/analytics.js

@@ -0,0 +1,45 @@
+// @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, options) {
+  if (!env.ANALYTICS_SERVICE)
+    return;
+  try {
+    const payload = {
+      ...body,
+      ...options?.indexes ? { indexes: [...options.indexes] } : {}
+    };
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const internalKey = env.INTERNAL_KEY_BINDING;
+    if (internalKey) {
+      headers["X-Internal-Auth-Key"] = internalKey;
+    }
+    await env.ANALYTICS_SERVICE.fetch(new Request(`http://localhost${endpoint}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload)
+    }));
+  } catch (e) {
+    console.error("Analytics tracking failed:", e);
+  }
+}
+export {
+  trackAnalytics
+};

package/dist/api-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * API Client — Bun fetch wrapper with AbortController timeouts, retry logic,
+ * and connection-aware error handling for the Hoox TUI dashboard.
+ *
+ * Auth headers come from the operator transport profile (Bearer + optional
+ * Cloudflare Access service-token headers). See `operator-transport.ts`.
+ *
+ * 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.
+ */
+import { type OperatorTransportEnv, type OperatorTransportProfile } from "./operator-transport";
+export declare class WorkerAPIError extends Error {
+    status: number;
+    retryable: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        retryable?: boolean;
+    });
+}
+export interface HooxFetchOptions extends RequestInit {
+    /** Injected transport profile (tests / multi-tenant callers). */
+    transport?: OperatorTransportProfile;
+    /** Env override when resolving transport (tests). */
+    transportEnv?: OperatorTransportEnv;
+}
+/**
+ * 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. "/v1/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?: HooxFetchOptions): 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;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAgB9B,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;AA+CD,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,iEAAiE;IACjE,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,qDAAqD;IACrD,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,CAAC,CAAC,CAsGZ"}

package/dist/api-client.js

@@ -0,0 +1,191 @@
+// @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/operator-transport.ts
+function stripTrailingSlashes(url) {
+  return url.replace(/\/+$/, "");
+}
+function parseTransport(raw) {
+  if (!raw)
+    return null;
+  const v = raw.trim().toLowerCase();
+  if (VALID_TRANSPORTS.has(v)) {
+    return v;
+  }
+  return null;
+}
+function resolveOperatorTransportProfile(env = process.env, options = {}) {
+  const accessClientId = env.CF_ACCESS_CLIENT_ID?.trim() ?? "";
+  const accessClientSecret = env.CF_ACCESS_CLIENT_SECRET?.trim() ?? "";
+  const hasAccess = Boolean(accessClientId && accessClientSecret);
+  const explicit = parseTransport(env.HOOX_TRANSPORT) ?? parseTransport(options.configTransport);
+  const transport = explicit ?? (hasAccess ? "access" : "public");
+  const apiFromEnv = env.HOOX_API_URL?.trim();
+  const apiFromConfig = options.configApiUrl?.trim();
+  const tokenFromEnv = env.HOOX_API_TOKEN?.trim();
+  const tokenFromConfig = options.configApiToken?.trim();
+  return {
+    transport,
+    apiBase: stripTrailingSlashes(apiFromEnv || apiFromConfig || DEFAULT_API_BASE),
+    bearerToken: tokenFromEnv || tokenFromConfig || "",
+    accessClientId,
+    accessClientSecret
+  };
+}
+function buildOperatorAuthHeaders(profile) {
+  const headers = {};
+  if (profile.bearerToken) {
+    headers.Authorization = `Bearer ${profile.bearerToken}`;
+  }
+  const useAccessHeaders = profile.transport === "access" || Boolean(profile.accessClientId) && Boolean(profile.accessClientSecret);
+  if (useAccessHeaders && profile.accessClientId && profile.accessClientSecret) {
+    headers["CF-Access-Client-Id"] = profile.accessClientId;
+    headers["CF-Access-Client-Secret"] = profile.accessClientSecret;
+  }
+  return headers;
+}
+function hasOperatorClientCredentials(profile) {
+  if (profile.bearerToken)
+    return true;
+  return Boolean(profile.accessClientId && profile.accessClientSecret);
+}
+function operatorUrl(profile, path) {
+  const base = profile.apiBase.replace(/\/+$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${p}`;
+}
+var DEFAULT_API_BASE = "http://localhost:8787", VALID_TRANSPORTS;
+var init_operator_transport = __esm(() => {
+  VALID_TRANSPORTS = new Set([
+    "public",
+    "access",
+    "mtls",
+    "tunnel"
+  ]);
+});
+
+// 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));
+}
+function activeProfile(override) {
+  return override ?? resolveOperatorTransportProfile();
+}
+async function hooxFetch(path, options) {
+  const profile = options?.transport ?? (options?.transportEnv ? resolveOperatorTransportProfile(options.transportEnv) : activeProfile());
+  const { transport: _t, transportEnv: _e, ...fetchInit } = 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 = operatorUrl(profile, path);
+      const headers = {
+        "Content-Type": "application/json",
+        ...buildOperatorAuthHeaders(profile),
+        ...fetchInit.headers
+      };
+      const response = await fetch(url, {
+        ...fetchInit,
+        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 FETCH_TIMEOUT_MS = 5000, MAX_RETRIES = 3, BASE_RETRY_DELAY_MS = 1000, MAX_RETRY_DELAY_MS = 16000, WorkerAPIError;
+var init_api_client = __esm(() => {
+  init_operator_transport();
+  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
+};