@jango-blockchained/hoox-shared 1.0.8

package/dist/d1/index.js

@@ -0,0 +1,316 @@
+// @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/errors.ts
+function toError(err, fallback = "Unknown error") {
+  if (err instanceof Error)
+    return err.message;
+  if (typeof err === "string")
+    return err;
+  if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
+    return err.message;
+  }
+  if (err === null || err === undefined)
+    return fallback;
+  try {
+    return JSON.stringify(err) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+function sanitizeOutput(data) {
+  if (data instanceof Error) {
+    return { name: data.name, message: data.message };
+  }
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const sanitized = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (k === "stack" || k === "cause")
+        continue;
+      sanitized[k] = v instanceof Error ? { name: v.name, message: v.message } : sanitizeOutput(v);
+    }
+    return sanitized;
+  }
+  if (Array.isArray(data)) {
+    return data.map(sanitizeOutput);
+  }
+  return data;
+}
+function createJsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(sanitizeOutput(data)), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function createSuccessResponse(result) {
+  return createJsonResponse({ success: true, result }, 200);
+}
+function createErrorResponse(error, status) {
+  const message = typeof error === "string" ? error : error.message;
+  const statusCode = typeof error === "string" ? status ?? 500 : error.status ?? 500;
+  const body = { success: false, error: message };
+  if (typeof error !== "string" && error.code)
+    body.code = error.code;
+  if (typeof error !== "string" && error.details !== undefined)
+    body.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: statusCode,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var Errors = {
+  badRequest: (message) => createErrorResponse({ message, status: 400, code: "BAD_REQUEST" }),
+  unauthorized: (message = "Unauthorized") => createErrorResponse({ message, status: 401, code: "UNAUTHORIZED" }),
+  forbidden: (message = "Forbidden") => createErrorResponse({ message, status: 403, code: "FORBIDDEN" }),
+  notFound: (message = "Not found") => createErrorResponse({ message, status: 404, code: "NOT_FOUND" }),
+  methodNotAllowed: (message = "Method not allowed") => createErrorResponse({ message, status: 405, code: "METHOD_NOT_ALLOWED" }),
+  rateLimited: (retryAfter) => {
+    const res = createErrorResponse({
+      message: "Rate limit exceeded",
+      status: 429,
+      code: "RATE_LIMITED"
+    });
+    if (retryAfter)
+      res.headers.set("Retry-After", String(retryAfter));
+    return res;
+  },
+  internal: (err) => {
+    const message = err ? toError(err, "Internal server error") : "Internal server error";
+    return createErrorResponse({
+      message,
+      status: 500,
+      code: "INTERNAL_ERROR"
+    });
+  }
+};
+
+// src/d1/repository.ts
+class D1Repository {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  async query(sql, params = []) {
+    try {
+      const stmt = this.db.prepare(sql).bind(...params);
+      const result = await stmt.all();
+      return {
+        success: result.success,
+        results: result.results,
+        error: result.error
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: toError(error)
+      };
+    }
+  }
+  async execute(sql, params = []) {
+    try {
+      const stmt = this.db.prepare(sql).bind(...params);
+      const result = await stmt.run();
+      return {
+        success: result.success,
+        meta: {
+          last_row_id: result.meta?.last_row_id,
+          changes: result.meta?.changes,
+          duration: result.meta?.duration
+        },
+        error: result.error
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: toError(error)
+      };
+    }
+  }
+  async batch(statements) {
+    try {
+      const prepared = statements.map((s) => s.params && s.params.length > 0 ? this.db.prepare(s.query).bind(...s.params) : this.db.prepare(s.query));
+      const results = await this.db.batch(...prepared);
+      return results.map((r) => ({
+        success: r.success,
+        meta: r.meta ? { last_row_id: r.meta.last_row_id, changes: r.meta.changes } : undefined,
+        error: r.error
+      }));
+    } catch (error) {
+      return statements.map(() => ({
+        success: false,
+        error: toError(error)
+      }));
+    }
+  }
+  prepare(sql) {
+    return this.db.prepare(sql);
+  }
+  async getTrades(limit = 50, offset = 0) {
+    return this.query("SELECT * FROM trades ORDER BY timestamp DESC LIMIT ? OFFSET ?", [limit, offset]);
+  }
+  async insertTrade(trade) {
+    return this.execute(`INSERT INTO trades (id, timestamp, exchange, symbol, action, quantity, price, leverage, status, raw_response) 
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      trade.id || crypto.randomUUID(),
+      trade.timestamp,
+      trade.exchange,
+      trade.symbol,
+      trade.action,
+      trade.quantity ?? null,
+      trade.price ?? null,
+      trade.leverage ?? null,
+      trade.status,
+      trade.raw_response ?? null
+    ]);
+  }
+  async getPositions(status) {
+    if (status) {
+      return this.query("SELECT * FROM positions WHERE status = ? ORDER BY updated_at DESC", [status]);
+    }
+    return this.query("SELECT * FROM positions ORDER BY updated_at DESC");
+  }
+  async upsertPosition(position) {
+    return this.execute(`REPLACE INTO positions (id, exchange, symbol, side, entry_price, mark_price, liquidation_price, leverage, size, unrealized_pnl, status, updated_at) 
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      position.id,
+      position.exchange,
+      position.symbol,
+      position.side,
+      position.entry_price ?? null,
+      position.mark_price ?? null,
+      position.liquidation_price ?? null,
+      position.leverage ?? null,
+      position.size,
+      position.unrealized_pnl ?? null,
+      position.status,
+      position.updated_at
+    ]);
+  }
+  async getTradeSignals(limit = 10) {
+    return this.query(`SELECT signal_id, timestamp, symbol, signal_type, source, processed_at 
+       FROM trade_signals 
+       ORDER BY processed_at DESC 
+       LIMIT ?`, [limit]);
+  }
+  async insertTradeSignal(signal) {
+    return this.execute(`INSERT INTO trade_signals (signal_id, timestamp, symbol, signal_type, source, raw_data) 
+       VALUES (?, ?, ?, ?, ?, ?)`, [
+      signal.signal_id,
+      signal.timestamp,
+      signal.symbol,
+      signal.signal_type,
+      signal.source ?? null,
+      signal.raw_data ?? null
+    ]);
+  }
+  async getSystemLogs(limit = 50) {
+    return this.query("SELECT * FROM system_logs ORDER BY timestamp DESC LIMIT ?", [limit]);
+  }
+  async insertSystemLog(log) {
+    return this.execute(`INSERT INTO system_logs (id, level, service, message, details) VALUES (?, ?, ?, ?, ?)`, [
+      log.id || crypto.randomUUID(),
+      log.level,
+      log.service,
+      log.message,
+      log.details ?? null
+    ]);
+  }
+  async getLatestBalances() {
+    return this.query(`
+      SELECT b.id, b.exchange, b.asset, b.total, b.free, b.used, b.timestamp
+      FROM balances b
+      INNER JOIN (
+        SELECT exchange, asset, MAX(timestamp) as max_time
+        FROM balances
+        GROUP BY exchange, asset
+      ) latest ON b.exchange = latest.exchange AND b.asset = latest.asset AND b.timestamp = latest.max_time
+    `);
+  }
+  async healthCheck() {
+    try {
+      await this.db.prepare("SELECT 1").first();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+// src/d1/schemas.ts
+import { z } from "zod";
+var TradeRecordSchema = z.object({
+  id: z.string(),
+  signal_id: z.string().nullable().optional(),
+  timestamp: z.number().int().positive(),
+  exchange: z.string().min(1),
+  symbol: z.string().min(1),
+  action: z.string().min(1),
+  quantity: z.number().nullable(),
+  price: z.number().nullable(),
+  leverage: z.number().nullable(),
+  status: z.string().min(1),
+  error_message: z.string().nullable().optional(),
+  raw_response: z.string().nullable().optional(),
+  created_at: z.number().int().optional()
+}).strict();
+var PositionRecordSchema = z.object({
+  id: z.string(),
+  exchange: z.string().min(1),
+  symbol: z.string().min(1),
+  side: z.enum(["LONG", "SHORT"]),
+  entry_price: z.number().nullable().optional(),
+  mark_price: z.number().nullable().optional(),
+  liquidation_price: z.number().nullable().optional(),
+  leverage: z.number().nullable().optional(),
+  size: z.number().nullable(),
+  unrealized_pnl: z.number().nullable().optional(),
+  status: z.enum(["OPEN", "CLOSED"]),
+  updated_at: z.number().int()
+}).strict();
+var BalanceRecordSchema = z.object({
+  id: z.string(),
+  exchange: z.string().min(1),
+  asset: z.string().min(1),
+  free: z.number().nullable(),
+  used: z.number().nullable(),
+  total: z.number().nullable(),
+  timestamp: z.number().int().positive()
+}).strict();
+var SystemLogRecordSchema = z.object({
+  id: z.string(),
+  timestamp: z.number().int().optional(),
+  level: z.string().min(1),
+  service: z.string().min(1),
+  message: z.string().min(1),
+  details: z.string().nullable().optional()
+}).strict();
+var TradeSignalRecordSchema = z.object({
+  signal_id: z.string(),
+  timestamp: z.number().int().positive(),
+  symbol: z.string().min(1),
+  signal_type: z.string().min(1),
+  source: z.string().nullable().optional(),
+  raw_data: z.string().nullable().optional(),
+  processed_at: z.number().int().optional()
+}).strict();
+export {
+  TradeSignalRecordSchema,
+  TradeRecordSchema,
+  SystemLogRecordSchema,
+  PositionRecordSchema,
+  D1Repository,
+  BalanceRecordSchema
+};

package/dist/d1/repository.d.ts

@@ -0,0 +1,77 @@
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types";
+import type { TradeRecord, PositionRecord, BalanceRecord, SystemLogRecord, TradeSignalRecord, D1QueryResult } from "./schemas";
+export interface BatchStatement {
+    query: string;
+    params?: unknown[];
+}
+/**
+ * Typed D1 repository providing convenience methods for the hoox database schema.
+ *
+ * Tables: trades, positions, balances, system_logs, trade_signals
+ */
+export declare class D1Repository {
+    private readonly db;
+    constructor(db: D1Database);
+    /**
+     * Execute a SELECT query and return typed results
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<D1QueryResult<T>>;
+    /**
+     * Execute a write query (INSERT, UPDATE, DELETE, REPLACE)
+     */
+    execute(sql: string, params?: unknown[]): Promise<D1QueryResult>;
+    /**
+     * Execute multiple statements in a batch transaction
+     */
+    batch(statements: BatchStatement[]): Promise<D1QueryResult[]>;
+    /**
+     * Return a raw D1PreparedStatement for complex or dynamic queries
+     */
+    prepare(sql: string): D1PreparedStatement;
+    /**
+     * Retrieve recent trades ordered by timestamp descending
+     */
+    getTrades(limit?: number, offset?: number): Promise<D1QueryResult<TradeRecord>>;
+    /**
+     * Insert a new trade record
+     */
+    insertTrade(trade: Omit<TradeRecord, "id" | "created_at"> & {
+        id?: string;
+    }): Promise<D1QueryResult>;
+    /**
+     * Retrieve positions, optionally filtered by status
+     */
+    getPositions(status?: "OPEN" | "CLOSED"): Promise<D1QueryResult<PositionRecord>>;
+    /**
+     * Upsert a position record (REPLACE INTO)
+     */
+    upsertPosition(position: PositionRecord): Promise<D1QueryResult>;
+    /**
+     * Retrieve recent trade signals
+     */
+    getTradeSignals(limit?: number): Promise<D1QueryResult<TradeSignalRecord>>;
+    /**
+     * Insert a new trade signal
+     */
+    insertTradeSignal(signal: TradeSignalRecord): Promise<D1QueryResult>;
+    /**
+     * Retrieve recent system logs
+     */
+    getSystemLogs(limit?: number): Promise<D1QueryResult<SystemLogRecord>>;
+    /**
+     * Insert a new system log entry (id and timestamp are auto-generated)
+     */
+    insertSystemLog(log: Pick<SystemLogRecord, "level" | "service" | "message"> & {
+        details?: string | null;
+        id?: string;
+    }): Promise<D1QueryResult>;
+    /**
+     * Retrieve the latest balance snapshot per exchange and asset
+     */
+    getLatestBalances(): Promise<D1QueryResult<BalanceRecord>>;
+    /**
+     * Quick health check — verifies the database connection is alive
+     */
+    healthCheck(): Promise<boolean>;
+}
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/d1/repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACd,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,UAAU;IAE3C;;OAEG;IACG,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAiB5B;;OAEG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAqB1E;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAuBnE;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB;IAMzC;;OAEG;IACG,SAAS,CACb,KAAK,GAAE,MAAW,EAClB,MAAM,GAAE,MAAU,GACjB,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IAOtC;;OAEG;IACG,WAAW,CACf,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,YAAY,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9D,OAAO,CAAC,aAAa,CAAC;IAmBzB;;OAEG;IACG,YAAY,CAChB,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GACzB,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC;IAYzC;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAqBtE;;OAEG;IACG,eAAe,CACnB,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAU5C;;OAEG;IACG,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAe1E;;OAEG;IACG,aAAa,CACjB,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;IAO1C;;OAEG;IACG,eAAe,CACnB,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG;QAC5D,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GACA,OAAO,CAAC,aAAa,CAAC;IAazB;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;IAYhE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAQtC"}

package/dist/d1/schemas.d.ts

@@ -0,0 +1,85 @@
+/**
+ * TypeScript interfaces for D1 database tables
+ * Based on the schema defined in workers/trade-worker/schema.sql
+ */
+import { z } from "zod";
+export declare const TradeRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    signal_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timestamp: z.ZodNumber;
+    exchange: z.ZodString;
+    symbol: z.ZodString;
+    action: z.ZodString;
+    quantity: z.ZodNullable<z.ZodNumber>;
+    price: z.ZodNullable<z.ZodNumber>;
+    leverage: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodString;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    raw_response: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const PositionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    exchange: z.ZodString;
+    symbol: z.ZodString;
+    side: z.ZodEnum<{
+        LONG: "LONG";
+        SHORT: "SHORT";
+    }>;
+    entry_price: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    mark_price: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    liquidation_price: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    leverage: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    size: z.ZodNullable<z.ZodNumber>;
+    unrealized_pnl: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    status: z.ZodEnum<{
+        OPEN: "OPEN";
+        CLOSED: "CLOSED";
+    }>;
+    updated_at: z.ZodNumber;
+}, z.core.$strict>;
+export declare const BalanceRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    exchange: z.ZodString;
+    asset: z.ZodString;
+    free: z.ZodNullable<z.ZodNumber>;
+    used: z.ZodNullable<z.ZodNumber>;
+    total: z.ZodNullable<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export declare const SystemLogRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+    level: z.ZodString;
+    service: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const TradeSignalRecordSchema: z.ZodObject<{
+    signal_id: z.ZodString;
+    timestamp: z.ZodNumber;
+    symbol: z.ZodString;
+    signal_type: z.ZodString;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    raw_data: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    processed_at: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type TradeRecord = z.infer<typeof TradeRecordSchema>;
+export type PositionRecord = z.infer<typeof PositionRecordSchema>;
+export type BalanceRecord = z.infer<typeof BalanceRecordSchema>;
+export type SystemLogRecord = z.infer<typeof SystemLogRecordSchema>;
+export type TradeSignalRecord = z.infer<typeof TradeSignalRecordSchema>;
+/**
+ * Generic D1 query result wrapper
+ */
+export interface D1QueryResult<T = unknown> {
+    success: boolean;
+    results?: T[];
+    error?: string;
+    meta?: {
+        last_row_id?: number;
+        changes?: number;
+        duration?: number;
+    };
+}
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/d1/schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;kBAgBnB,CAAC;AAEZ,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;kBAetB,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;;;;;;;kBAUrB,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;;;;;kBASvB,CAAC;AAEZ,eAAO,MAAM,uBAAuB;;;;;;;;kBAUzB,CAAC;AAIZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE;QACL,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH"}

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Error handling utilities for Cloudflare Workers and Dashboard
+ * Centralizes error response creation across the monorepo
+ */
+import type { AppError } from "./types/errors";
+/**
+ * Safely extract an error message from any caught value.
+ * Eliminates the duplicated `error instanceof Error ? error.message : String(error)`
+ * pattern that appears ~40+ times across the codebase.
+ *
+ * @example
+ * try { ... } catch (err) {
+ *   console.error(toError(err));
+ * }
+ */
+export declare function toError(err: unknown, fallback?: string): string;
+export declare function createJsonResponse(data: unknown, status?: number): Response;
+/**
+ * Create a success response with standard format
+ */
+export declare function createSuccessResponse(result?: unknown): Response;
+/**
+ * Create a Cloudflare Worker error response
+ * Includes `success: false` in the response body for consistent client-side handling
+ */
+export declare function createErrorResponse(error: AppError | string, status?: number): Response;
+/**
+ * Predefined error factories for common error types
+ */
+export declare const Errors: {
+    badRequest: (message: string) => Response;
+    unauthorized: (message?: string) => Response;
+    forbidden: (message?: string) => Response;
+    notFound: (message?: string) => Response;
+    methodNotAllowed: (message?: string) => Response;
+    rateLimited: (retryAfter?: number) => Response;
+    internal: (err?: unknown) => Response;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAkB,GAAG,MAAM,CAkBxE;AA+BD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,SAAM,GAAG,QAAQ,CAKxE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEhE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,QAAQ,CAcV;AAED;;GAEG;AACH,eAAO,MAAM,MAAM;0BACK,MAAM;;;;;+BAUD,MAAM;qBAShB,OAAO;CAUzB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,106 @@
+// @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/errors.ts
+function toError(err, fallback = "Unknown error") {
+  if (err instanceof Error)
+    return err.message;
+  if (typeof err === "string")
+    return err;
+  if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
+    return err.message;
+  }
+  if (err === null || err === undefined)
+    return fallback;
+  try {
+    return JSON.stringify(err) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+function sanitizeOutput(data) {
+  if (data instanceof Error) {
+    return { name: data.name, message: data.message };
+  }
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const sanitized = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (k === "stack" || k === "cause")
+        continue;
+      sanitized[k] = v instanceof Error ? { name: v.name, message: v.message } : sanitizeOutput(v);
+    }
+    return sanitized;
+  }
+  if (Array.isArray(data)) {
+    return data.map(sanitizeOutput);
+  }
+  return data;
+}
+function createJsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(sanitizeOutput(data)), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function createSuccessResponse(result) {
+  return createJsonResponse({ success: true, result }, 200);
+}
+function createErrorResponse(error, status) {
+  const message = typeof error === "string" ? error : error.message;
+  const statusCode = typeof error === "string" ? status ?? 500 : error.status ?? 500;
+  const body = { success: false, error: message };
+  if (typeof error !== "string" && error.code)
+    body.code = error.code;
+  if (typeof error !== "string" && error.details !== undefined)
+    body.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: statusCode,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var Errors = {
+  badRequest: (message) => createErrorResponse({ message, status: 400, code: "BAD_REQUEST" }),
+  unauthorized: (message = "Unauthorized") => createErrorResponse({ message, status: 401, code: "UNAUTHORIZED" }),
+  forbidden: (message = "Forbidden") => createErrorResponse({ message, status: 403, code: "FORBIDDEN" }),
+  notFound: (message = "Not found") => createErrorResponse({ message, status: 404, code: "NOT_FOUND" }),
+  methodNotAllowed: (message = "Method not allowed") => createErrorResponse({ message, status: 405, code: "METHOD_NOT_ALLOWED" }),
+  rateLimited: (retryAfter) => {
+    const res = createErrorResponse({
+      message: "Rate limit exceeded",
+      status: 429,
+      code: "RATE_LIMITED"
+    });
+    if (retryAfter)
+      res.headers.set("Retry-After", String(retryAfter));
+    return res;
+  },
+  internal: (err) => {
+    const message = err ? toError(err, "Internal server error") : "Internal server error";
+    return createErrorResponse({
+      message,
+      status: 500,
+      code: "INTERNAL_ERROR"
+    });
+  }
+};
+export {
+  toError,
+  createSuccessResponse,
+  createJsonResponse,
+  createErrorResponse,
+  Errors
+};