@wopr-network/platform-ui-core 1.0.0

package/src/lib/errors.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { ApiError, AppError, NetworkError, toUserMessage, ValidationError } from "./errors";
+
+describe("error classes", () => {
+  it("ApiError carries status and statusText", () => {
+    const err = new ApiError(404, "Not Found");
+    expect(err).toBeInstanceOf(AppError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("ApiError");
+    expect(err.status).toBe(404);
+    expect(err.statusText).toBe("Not Found");
+    expect(err.message).toBe("API error: 404 Not Found");
+  });
+
+  it("ApiError accepts custom message", () => {
+    const err = new ApiError(422, "Unprocessable", "Invalid bot name");
+    expect(err.message).toBe("Invalid bot name");
+    expect(err.status).toBe(422);
+  });
+
+  it("ValidationError carries optional field", () => {
+    const err = new ValidationError("Name is required", "name");
+    expect(err).toBeInstanceOf(AppError);
+    expect(err.name).toBe("ValidationError");
+    expect(err.field).toBe("name");
+    expect(err.message).toBe("Name is required");
+  });
+
+  it("ValidationError works without field", () => {
+    const err = new ValidationError("Invalid input");
+    expect(err.field).toBeUndefined();
+  });
+
+  it("NetworkError has sensible default message", () => {
+    const err = new NetworkError();
+    expect(err).toBeInstanceOf(AppError);
+    expect(err.name).toBe("NetworkError");
+    expect(err.message).toBe("A network error occurred. Please try again.");
+  });
+});
+
+describe("toUserMessage", () => {
+  it("extracts message from Error", () => {
+    expect(toUserMessage(new Error("boom"))).toBe("boom");
+  });
+
+  it("extracts message from ApiError", () => {
+    expect(toUserMessage(new ApiError(500, "Internal"))).toBe("API error: 500 Internal");
+  });
+
+  it("returns string as-is", () => {
+    expect(toUserMessage("oops")).toBe("oops");
+  });
+
+  it("returns fallback for non-Error objects", () => {
+    expect(toUserMessage(42)).toBe("Something went wrong. Please try again.");
+    expect(toUserMessage(null)).toBe("Something went wrong. Please try again.");
+    expect(toUserMessage(undefined)).toBe("Something went wrong. Please try again.");
+  });
+
+  it("accepts custom fallback", () => {
+    expect(toUserMessage({}, "Custom fallback")).toBe("Custom fallback");
+  });
+});

package/src/lib/errors.ts

@@ -0,0 +1,52 @@
+/** Base class for all platform errors. */
+export class AppError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AppError";
+  }
+}
+
+/** Thrown when an API request returns a non-2xx status. */
+export class ApiError extends AppError {
+  readonly status: number;
+  readonly statusText: string;
+
+  constructor(status: number, statusText: string, message?: string) {
+    super(message ?? `API error: ${status} ${statusText}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.statusText = statusText;
+  }
+}
+
+/** Thrown for client-side validation failures (form fields, input checks). */
+export class ValidationError extends AppError {
+  readonly field?: string;
+
+  constructor(message: string, field?: string) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+  }
+}
+
+/** Thrown when a fetch fails due to network issues (no response received). */
+export class NetworkError extends AppError {
+  constructor(message = "A network error occurred. Please try again.") {
+    super(message);
+    this.name = "NetworkError";
+  }
+}
+
+/**
+ * Extract a user-friendly message from any thrown value.
+ * Use in catch blocks: `setError(toUserMessage(err))`
+ */
+export function toUserMessage(
+  err: unknown,
+  fallback = "Something went wrong. Please try again.",
+): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  return fallback;
+}

package/src/lib/fetch-utils.test.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { handleUnauthorized, UnauthorizedError } from "./fetch-utils";
+
+describe("UnauthorizedError", () => {
+  it("has default message", () => {
+    const err = new UnauthorizedError();
+    expect(err.message).toBe("Session expired");
+    expect(err.name).toBe("UnauthorizedError");
+  });
+
+  it("accepts custom message", () => {
+    const err = new UnauthorizedError("Token revoked");
+    expect(err.message).toBe("Token revoked");
+  });
+
+  it("is an instance of Error", () => {
+    expect(new UnauthorizedError()).toBeInstanceOf(Error);
+  });
+});
+
+describe("handleUnauthorized", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("always throws UnauthorizedError", () => {
+    expect(() => handleUnauthorized()).toThrow(UnauthorizedError);
+  });
+
+  it("sets window.location.href to login URL with callbackUrl", () => {
+    Object.defineProperty(window, "location", {
+      value: {
+        pathname: "/dashboard",
+        search: "?tab=fleet",
+        href: "",
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    try {
+      handleUnauthorized();
+    } catch {
+      // expected
+    }
+
+    expect(window.location.href).toBe(
+      "/login?reason=expired&callbackUrl=%2Fdashboard%3Ftab%3Dfleet",
+    );
+
+    Object.defineProperty(window, "location", {
+      value: { pathname: "/", search: "", href: "" },
+      writable: true,
+      configurable: true,
+    });
+  });
+});

package/src/lib/fetch-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Custom error for 401 Unauthorized responses.
+ * Thrown after triggering a redirect to /login, so call sites can
+ * identify auth failures if they catch before the redirect completes.
+ */
+export class UnauthorizedError extends Error {
+  constructor(message = "Session expired") {
+    super(message);
+    this.name = "UnauthorizedError";
+  }
+}
+
+/**
+ * Handle a 401 response by redirecting to /login with a callbackUrl.
+ * Only runs on the client (checks `typeof window`).
+ * Throws UnauthorizedError after initiating redirect.
+ */
+export function handleUnauthorized(): never {
+  if (typeof window !== "undefined") {
+    const callbackUrl = window.location.pathname + window.location.search;
+    const loginUrl = `/login?reason=expired&callbackUrl=${encodeURIComponent(callbackUrl)}`;
+    window.location.href = loginUrl;
+  }
+  throw new UnauthorizedError();
+}

package/src/lib/format-credit.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { formatCreditDetailed, formatCreditStandard } from "./format-credit";
+
+describe("formatCreditStandard", () => {
+  it("formats whole dollars with 2 decimal places", () => {
+    expect(formatCreditStandard(5)).toBe("$5.00");
+  });
+
+  it("formats fractional dollars", () => {
+    expect(formatCreditStandard(1.5)).toBe("$1.50");
+  });
+
+  it("formats zero", () => {
+    expect(formatCreditStandard(0)).toBe("$0.00");
+  });
+
+  it("rounds to 2 decimal places", () => {
+    expect(formatCreditStandard(1.999)).toBe("$2.00");
+  });
+
+  it("formats large values", () => {
+    expect(formatCreditStandard(1000)).toBe("$1000.00");
+  });
+
+  it("formats small fractional values", () => {
+    expect(formatCreditStandard(0.01)).toBe("$0.01");
+  });
+});
+
+describe("formatCreditDetailed", () => {
+  it("formats standard 2-decimal values", () => {
+    expect(formatCreditDetailed(1.23)).toBe("$1.23");
+  });
+
+  it("preserves nanodollar precision", () => {
+    expect(formatCreditDetailed(0.000001)).toBe("$0.000001");
+  });
+
+  it("trims trailing zeros beyond 2 places", () => {
+    expect(formatCreditDetailed(1.5)).toBe("$1.50");
+  });
+
+  it("keeps minimum 2 decimal places for whole numbers", () => {
+    expect(formatCreditDetailed(5)).toBe("$5.00");
+  });
+
+  it("keeps minimum 2 decimal places for zero", () => {
+    expect(formatCreditDetailed(0)).toBe("$0.00");
+  });
+
+  it("trims only trailing zeros", () => {
+    expect(formatCreditDetailed(0.001)).toBe("$0.001");
+  });
+
+  it("handles values with exactly 2 significant decimals", () => {
+    expect(formatCreditDetailed(0.01)).toBe("$0.01");
+  });
+
+  it("pads single significant decimal to 2", () => {
+    expect(formatCreditDetailed(1.1)).toBe("$1.10");
+  });
+
+  it("handles very small values", () => {
+    expect(formatCreditDetailed(0.000000001)).toBe("$0.000000001");
+  });
+});

package/src/lib/format-credit.ts

@@ -0,0 +1,24 @@
+/**
+ * Format a dollar value for standard display (balances, invoices, top-ups).
+ * Always exactly 2 decimal places: "$5.00"
+ */
+export function formatCreditStandard(dollars: number): string {
+  return `$${dollars.toFixed(2)}`;
+}
+
+/**
+ * Format a dollar value for detailed/breakdown display (per-request costs, ledger rows).
+ * Up to 9 decimal places (nanodollar precision), trailing zeros trimmed,
+ * minimum 2 decimal places: "$0.000001", "$0.01", "$1.23"
+ */
+export function formatCreditDetailed(dollars: number): string {
+  const full = dollars.toFixed(9);
+  const dotIndex = full.indexOf(".");
+  const whole = full.slice(0, dotIndex);
+  const frac = full.slice(dotIndex + 1);
+  let trimmed = frac.replace(/0+$/, "");
+  if (trimmed.length < 2) {
+    trimmed = trimmed.padEnd(2, "0");
+  }
+  return `$${whole}.${trimmed}`;
+}

package/src/lib/format.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { formatRelativeTime } from "./format";
+
+describe("formatRelativeTime", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2025-06-15T12:00:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns 'just now' for less than 60 seconds ago", () => {
+    const thirtySecsAgo = new Date("2025-06-15T11:59:30Z");
+    expect(formatRelativeTime(thirtySecsAgo)).toBe("just now");
+  });
+
+  it("returns 'just now' for 0 seconds ago", () => {
+    const now = new Date("2025-06-15T12:00:00Z");
+    expect(formatRelativeTime(now)).toBe("just now");
+  });
+
+  it("returns minutes ago", () => {
+    const fiveMinsAgo = new Date("2025-06-15T11:55:00Z");
+    expect(formatRelativeTime(fiveMinsAgo)).toBe("5m ago");
+  });
+
+  it("returns 1m ago at exactly 60 seconds", () => {
+    const oneMinAgo = new Date("2025-06-15T11:59:00Z");
+    expect(formatRelativeTime(oneMinAgo)).toBe("1m ago");
+  });
+
+  it("returns hours ago", () => {
+    const threeHoursAgo = new Date("2025-06-15T09:00:00Z");
+    expect(formatRelativeTime(threeHoursAgo)).toBe("3h ago");
+  });
+
+  it("returns 1h ago at exactly 60 minutes", () => {
+    const oneHourAgo = new Date("2025-06-15T11:00:00Z");
+    expect(formatRelativeTime(oneHourAgo)).toBe("1h ago");
+  });
+
+  it("returns days ago", () => {
+    const twoDaysAgo = new Date("2025-06-13T12:00:00Z");
+    expect(formatRelativeTime(twoDaysAgo)).toBe("2d ago");
+  });
+
+  it("returns 1d ago at exactly 24 hours", () => {
+    const oneDayAgo = new Date("2025-06-14T12:00:00Z");
+    expect(formatRelativeTime(oneDayAgo)).toBe("1d ago");
+  });
+
+  it("accepts ISO string input", () => {
+    expect(formatRelativeTime("2025-06-15T11:55:00Z")).toBe("5m ago");
+  });
+
+  it("handles large day counts", () => {
+    const thirtyDaysAgo = new Date("2025-05-16T12:00:00Z");
+    expect(formatRelativeTime(thirtyDaysAgo)).toBe("30d ago");
+  });
+});

package/src/lib/format.ts

@@ -0,0 +1,17 @@
+/**
+ * Format a timestamp as relative time (e.g., "just now", "2m ago", "1h ago").
+ * Accepts a Date object or ISO string.
+ */
+export function formatRelativeTime(timestamp: Date | string): string {
+  const now = Date.now();
+  const then = typeof timestamp === "string" ? new Date(timestamp).getTime() : timestamp.getTime();
+  const diffSeconds = Math.floor((now - then) / 1000);
+
+  if (diffSeconds < 60) return "just now";
+  const diffMinutes = Math.floor(diffSeconds / 60);
+  if (diffMinutes < 60) return `${diffMinutes}m ago`;
+  const diffHours = Math.floor(diffMinutes / 60);
+  if (diffHours < 24) return `${diffHours}h ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  return `${diffDays}d ago`;
+}

package/src/lib/logger.ts

@@ -0,0 +1,28 @@
+/**
+ * Structured logger for platform-ui-core.
+ *
+ * Wraps console.warn / console.error with a namespace tag so log lines are
+ * easy to filter and grep in production log streams.
+ *
+ * Usage:
+ *   import { logger } from "@/lib/logger";
+ *   const log = logger("my-module");
+ *   log.warn("Something degraded", { key: "value" });
+ *   log.error("Fatal in handler", err);
+ */
+
+export interface Logger {
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+export function logger(namespace: string): Logger {
+  return {
+    warn(message: string, ...args: unknown[]) {
+      console.warn(`[${namespace}] ${message}`, ...args);
+    },
+    error(message: string, ...args: unknown[]) {
+      console.error(`[${namespace}] ${message}`, ...args);
+    },
+  };
+}