@enderworld/onlyapi 1.5.1

package/src/core/types/result.ts

@@ -0,0 +1,52 @@
+/**
+ * Result monad — eliminates throw-based control flow.
+ * Every fallible operation returns Result<T, E> instead of throwing.
+ */
+
+export type Result<T, E = AppError> = Ok<T> | Err<E>;
+
+export interface Ok<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+export interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+
+export const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
+export const err = <E>(error: E): Err<E> => ({ ok: false, error });
+
+/** Map over the success value */
+export const map = <T, U, E>(result: Result<T, E>, fn: (v: T) => U): Result<U, E> =>
+  result.ok ? ok(fn(result.value)) : result;
+
+/** FlatMap / chain */
+export const flatMap = <T, U, E>(result: Result<T, E>, fn: (v: T) => Result<U, E>): Result<U, E> =>
+  result.ok ? fn(result.value) : result;
+
+/** Unwrap with a default */
+export const unwrapOr = <T, E>(result: Result<T, E>, fallback: T): T =>
+  result.ok ? result.value : fallback;
+
+/** Wrap a throwing function into a Result */
+export const tryCatch = <T>(fn: () => T): Result<T, unknown> => {
+  try {
+    return ok(fn());
+  } catch (e: unknown) {
+    return err(e);
+  }
+};
+
+/** Wrap an async throwing function into a Result */
+export const tryCatchAsync = async <T>(fn: () => Promise<T>): Promise<Result<T, unknown>> => {
+  try {
+    return ok(await fn());
+  } catch (e: unknown) {
+    return err(e);
+  }
+};
+
+// Re-export the error type referenced above
+import type { AppError } from "../errors/app-error.js";

package/src/infrastructure/alerting/index.ts

@@ -0,0 +1 @@
+export { createWebhookAlertSink, createNoopAlertSink } from "./webhook.js";

package/src/infrastructure/alerting/webhook.ts

@@ -0,0 +1,100 @@
+/**
+ * Webhook alert sink — sends alert notifications to configured webhook URLs.
+ *
+ * Features:
+ *   - HTTP POST with JSON payload
+ *   - Retry with backoff on transient failures
+ *   - Configurable via ALERT_WEBHOOK_URL env var
+ *   - Non-blocking — fire-and-forget with error logging
+ */
+
+import type { AlertPayload, AlertSink } from "../../core/ports/alert-sink.js";
+import type { Logger } from "../../core/ports/logger.js";
+
+interface WebhookAlertSinkOptions {
+  /** Webhook URL to POST alerts to */
+  readonly url: string;
+  /** Request timeout in ms (default: 5000) */
+  readonly timeoutMs?: number;
+  /** Max retry attempts (default: 2) */
+  readonly maxRetries?: number;
+  /** Logger for error reporting */
+  readonly logger: Logger;
+}
+
+export const createWebhookAlertSink = (options: WebhookAlertSinkOptions): AlertSink => {
+  const { url, logger } = options;
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const maxRetries = options.maxRetries ?? 2;
+
+  return {
+    get enabled(): boolean {
+      return url.length > 0;
+    },
+
+    async send(payload: AlertPayload): Promise<void> {
+      const body = JSON.stringify(payload);
+      let lastError: unknown;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const controller = new AbortController();
+          const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+          const response = await fetch(url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "User-Agent": "onlyApi/1.3.0",
+            },
+            body,
+            signal: controller.signal,
+          });
+
+          clearTimeout(timer);
+
+          if (response.ok) {
+            logger.debug("Alert sent successfully", {
+              level: payload.level,
+              title: payload.title,
+              attempt: attempt + 1,
+            });
+            return;
+          }
+
+          lastError = new Error(`Webhook returned ${response.status}`);
+          logger.warn("Alert webhook returned non-OK status", {
+            status: response.status,
+            attempt: attempt + 1,
+          });
+        } catch (error: unknown) {
+          lastError = error;
+          if (attempt < maxRetries) {
+            // Exponential backoff: 500ms, 1000ms
+            const delay = 500 * 2 ** attempt;
+            await new Promise((r) => setTimeout(r, delay));
+          }
+        }
+      }
+
+      logger.error("Failed to send alert after retries", {
+        level: payload.level,
+        title: payload.title,
+        error: lastError instanceof Error ? lastError.message : String(lastError),
+        maxRetries,
+      });
+    },
+  };
+};
+
+/**
+ * No-op alert sink for when no webhook URL is configured.
+ */
+export const createNoopAlertSink = (): AlertSink => ({
+  get enabled(): boolean {
+    return false;
+  },
+  async send(_payload: AlertPayload): Promise<void> {
+    // intentionally empty — no webhook configured
+  },
+});

package/src/infrastructure/cache/in-memory-cache.ts

@@ -0,0 +1,111 @@
+/**
+ * In-memory cache — zero-dep implementation for development / single-process.
+ * Swap with Redis adapter for production multi-process deployments.
+ */
+
+import { internal } from "../../core/errors/app-error.js";
+import type { AppError } from "../../core/errors/app-error.js";
+import type { Cache } from "../../core/ports/cache.js";
+import { type Result, err, ok } from "../../core/types/result.js";
+
+interface CacheEntry<T = unknown> {
+  value: T;
+  expiresAt: number | null; // null = no expiry
+}
+
+export const createInMemoryCache = (): Cache => {
+  const store = new Map<string, CacheEntry>();
+
+  /** Remove expired entries lazily */
+  const isExpired = (entry: CacheEntry): boolean =>
+    entry.expiresAt !== null && entry.expiresAt <= Date.now();
+
+  return {
+    async get<T = unknown>(key: string): Promise<Result<T | null, AppError>> {
+      try {
+        const entry = store.get(key);
+        if (!entry || isExpired(entry)) {
+          if (entry) store.delete(key);
+          return ok(null);
+        }
+        return ok(entry.value as T);
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<Result<void, AppError>> {
+      try {
+        store.set(key, {
+          value,
+          expiresAt: ttlMs !== undefined ? Date.now() + ttlMs : null,
+        });
+        return ok(undefined);
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async del(key: string): Promise<Result<boolean, AppError>> {
+      try {
+        return ok(store.delete(key));
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async has(key: string): Promise<Result<boolean, AppError>> {
+      try {
+        const entry = store.get(key);
+        if (!entry || isExpired(entry)) {
+          if (entry) store.delete(key);
+          return ok(false);
+        }
+        return ok(true);
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async incr(key: string, delta = 1): Promise<Result<number, AppError>> {
+      try {
+        const entry = store.get(key);
+        if (!entry || isExpired(entry)) {
+          store.set(key, { value: delta, expiresAt: entry?.expiresAt ?? null });
+          return ok(delta);
+        }
+        const newVal = (entry.value as number) + delta;
+        entry.value = newVal;
+        return ok(newVal);
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async delPattern(pattern: string): Promise<Result<number, AppError>> {
+      try {
+        // Convert glob pattern to regex
+        const regexStr = pattern
+          .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, ".*")
+          .replace(/\?/g, ".");
+        const regex = new RegExp(`^${regexStr}$`);
+
+        let count = 0;
+        for (const key of store.keys()) {
+          if (regex.test(key)) {
+            store.delete(key);
+            count++;
+          }
+        }
+        return ok(count);
+      } catch (e: unknown) {
+        return err(internal("Cache error", e));
+      }
+    },
+
+    async close(): Promise<void> {
+      store.clear();
+    },
+  };
+};

package/src/infrastructure/cache/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Cache adapters — barrel export.
+ */
+
+export { createInMemoryCache } from "./in-memory-cache.js";
+export { createRedisCache } from "./redis-cache.js";

package/src/infrastructure/cache/redis-cache.ts

@@ -0,0 +1,204 @@
+/**
+ * Redis cache adapter — using raw TCP via Bun.connect().
+ *
+ * Zero external dependencies. Implements the RESP (Redis Serialization Protocol)
+ * directly over a TCP socket. Supports: GET, SET, DEL, EXISTS, INCRBY, KEYS, QUIT.
+ *
+ * For production, considers connection pooling. This single-connection adapter
+ * is suitable for moderate load. Swap to ioredis or similar for advanced features.
+ */
+
+import { internal } from "../../core/errors/app-error.js";
+import type { AppError } from "../../core/errors/app-error.js";
+import type { Cache } from "../../core/ports/cache.js";
+import type { Logger } from "../../core/ports/logger.js";
+import { type Result, err, ok } from "../../core/types/result.js";
+
+interface RedisConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly password?: string | undefined;
+  readonly db?: number | undefined;
+}
+
+interface RedisCacheDeps {
+  readonly config: RedisConfig;
+  readonly logger: Logger;
+}
+
+/**
+ * Encode a RESP command: *<n>\r\n$<len>\r\n<arg>\r\n...
+ */
+const encodeCommand = (args: readonly string[]): string => {
+  let cmd = `*${args.length}\r\n`;
+  for (const arg of args) {
+    cmd += `$${Buffer.byteLength(arg)}\r\n${arg}\r\n`;
+  }
+  return cmd;
+};
+
+export const createRedisCache = async (deps: RedisCacheDeps): Promise<Cache> => {
+  const { config, logger } = deps;
+
+  let responseBuffer = "";
+  let resolveResponse: ((value: string) => void) | null = null;
+
+  const socket = await Bun.connect({
+    hostname: config.host,
+    port: config.port,
+    socket: {
+      data(_socket, data) {
+        responseBuffer += data.toString();
+        if (resolveResponse && responseBuffer.includes("\r\n")) {
+          const resolve = resolveResponse;
+          resolveResponse = null;
+          resolve(responseBuffer);
+          responseBuffer = "";
+        }
+      },
+      open() {
+        logger.debug("Redis connection established", {
+          host: config.host,
+          port: config.port,
+        });
+      },
+      close() {
+        logger.debug("Redis connection closed");
+      },
+      error(_socket, error) {
+        logger.error("Redis connection error", { error: error.message });
+      },
+    },
+  });
+
+  const sendCommand = async (args: readonly string[]): Promise<string> => {
+    const cmd = encodeCommand(args);
+    return new Promise<string>((resolve) => {
+      resolveResponse = resolve;
+      socket.write(cmd);
+    });
+  };
+
+  /**
+   * Parse a simple RESP response.
+   * +OK, -ERR, :42, $-1 (nil), $5\r\nhello
+   */
+  const parseResponse = (raw: string): string | null => {
+    if (raw.startsWith("+")) return raw.substring(1, raw.indexOf("\r\n"));
+    if (raw.startsWith("-")) throw new Error(raw.substring(1, raw.indexOf("\r\n")));
+    if (raw.startsWith(":")) return raw.substring(1, raw.indexOf("\r\n"));
+    if (raw.startsWith("$-1")) return null;
+    if (raw.startsWith("$")) {
+      const firstNewline = raw.indexOf("\r\n");
+      const dataStart = firstNewline + 2;
+      const len = Number.parseInt(raw.substring(1, firstNewline), 10);
+      return raw.substring(dataStart, dataStart + len);
+    }
+    return raw;
+  };
+
+  // Authenticate if password provided
+  if (config.password) {
+    await sendCommand(["AUTH", config.password]);
+  }
+  // Select database if specified
+  if (config.db !== undefined) {
+    await sendCommand(["SELECT", String(config.db)]);
+  }
+
+  return {
+    async get<T = unknown>(key: string): Promise<Result<T | null, AppError>> {
+      try {
+        const raw = await sendCommand(["GET", key]);
+        const value = parseResponse(raw);
+        if (value === null) return ok(null);
+        try {
+          return ok(JSON.parse(value) as T);
+        } catch {
+          return ok(value as T);
+        }
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<Result<void, AppError>> {
+      try {
+        const serialized = typeof value === "string" ? value : JSON.stringify(value);
+        if (ttlMs !== undefined) {
+          await sendCommand(["SET", key, serialized, "PX", String(ttlMs)]);
+        } else {
+          await sendCommand(["SET", key, serialized]);
+        }
+        return ok(undefined);
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async del(key: string): Promise<Result<boolean, AppError>> {
+      try {
+        const raw = await sendCommand(["DEL", key]);
+        const value = parseResponse(raw);
+        return ok(value === "1");
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async has(key: string): Promise<Result<boolean, AppError>> {
+      try {
+        const raw = await sendCommand(["EXISTS", key]);
+        const value = parseResponse(raw);
+        return ok(value === "1");
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async incr(key: string, delta = 1): Promise<Result<number, AppError>> {
+      try {
+        const raw = await sendCommand(["INCRBY", key, String(delta)]);
+        const value = parseResponse(raw);
+        return ok(Number(value));
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async delPattern(pattern: string): Promise<Result<number, AppError>> {
+      try {
+        // KEYS is O(n) — acceptable for admin/maintenance operations
+        const raw = await sendCommand(["KEYS", pattern]);
+        // Parse array response
+        if (raw.startsWith("*0")) return ok(0);
+
+        const lines = raw.split("\r\n").filter(Boolean);
+        const keys: string[] = [];
+        for (let i = 1; i < lines.length; i++) {
+          const line = lines[i];
+          if (line && !line.startsWith("$")) {
+            keys.push(line);
+          }
+        }
+
+        if (keys.length === 0) return ok(0);
+
+        const delRaw = await sendCommand(["DEL", ...keys]);
+        const delVal = parseResponse(delRaw);
+        return ok(Number(delVal));
+      } catch (e: unknown) {
+        return err(internal("Redis error", e));
+      }
+    },
+
+    async close(): Promise<void> {
+      try {
+        await sendCommand(["QUIT"]);
+      } catch {
+        // Ignore errors during close
+      }
+      socket.end();
+    },
+  };
+};

package/src/infrastructure/config/config.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { printConfigError } from "../../shared/cli.js";
+
+/**
+ * Application config — validated at boot via Zod.
+ * Fails fast with clear messages if env vars are missing.
+ */
+const configSchema = z.object({
+  env: z.enum(["development", "production", "test"]).default("development"),
+  port: z.coerce.number().int().min(1).max(65535).default(3000),
+  host: z.string().min(1).default("0.0.0.0"),
+
+  jwt: z.object({
+    secret: z.string().min(32),
+    expiresIn: z.string().default("15m"),
+    refreshExpiresIn: z.string().default("7d"),
+  }),
+
+  cors: z.object({
+    origins: z
+      .string()
+      .transform((s) => s.split(",").map((o) => o.trim()))
+      .default("*"),
+  }),
+
+  rateLimit: z.object({
+    windowMs: z.coerce.number().int().positive().default(60_000),
+    maxRequests: z.coerce.number().int().positive().default(100),
+  }),
+
+  log: z.object({
+    level: z.enum(["debug", "info", "warn", "error", "fatal"]).default("info"),
+    format: z.enum(["pretty", "json"]).default("pretty"),
+  }),
+
+  database: z.object({
+    driver: z.enum(["sqlite", "postgres", "mssql"]).default("sqlite"),
+    url: z.string().optional(),
+    path: z.string().default("data/onlyapi.sqlite"),
+  }),
+
+  redis: z.object({
+    enabled: z
+      .enum(["true", "false"])
+      .transform((v) => v === "true")
+      .default("false"),
+    host: z.string().default("127.0.0.1"),
+    port: z.coerce.number().int().min(1).max(65535).default(6379),
+    password: z.string().optional(),
+    db: z.coerce.number().int().min(0).max(15).default(0),
+  }),
+
+  i18n: z.object({
+    defaultLocale: z.string().default("en"),
+    supportedLocales: z
+      .string()
+      .transform((s) => s.split(",").map((l) => l.trim()))
+      .default("en"),
+  }),
+
+  lockout: z.object({
+    maxAttempts: z.coerce.number().int().positive().default(5),
+    durationMs: z.coerce.number().int().positive().default(900_000), // 15 minutes
+  }),
+
+  alerting: z.object({
+    webhookUrl: z.string().url().optional(),
+    timeoutMs: z.coerce.number().int().positive().default(5_000),
+  }),
+
+  circuitBreaker: z.object({
+    failureThreshold: z.coerce.number().int().positive().default(5),
+    resetTimeoutMs: z.coerce.number().int().positive().default(30_000),
+    halfOpenSuccessThreshold: z.coerce.number().int().positive().default(2),
+  }),
+
+  passwordPolicy: z.object({
+    minLength: z.coerce.number().int().positive().default(8),
+    requireUppercase: z
+      .enum(["true", "false"])
+      .transform((v) => v === "true")
+      .default("true"),
+    requireLowercase: z
+      .enum(["true", "false"])
+      .transform((v) => v === "true")
+      .default("true"),
+    requireDigit: z
+      .enum(["true", "false"])
+      .transform((v) => v === "true")
+      .default("true"),
+    requireSpecial: z
+      .enum(["true", "false"])
+      .transform((v) => v === "true")
+      .default("false"),
+    historyCount: z.coerce.number().int().min(0).default(5),
+    maxAgeDays: z.coerce.number().int().min(0).default(0),
+  }),
+
+  oauth: z.object({
+    googleClientId: z.string().optional(),
+    googleClientSecret: z.string().optional(),
+    githubClientId: z.string().optional(),
+    githubClientSecret: z.string().optional(),
+  }),
+});
+
+export type AppConfig = z.infer<typeof configSchema>;
+
+export const loadConfig = (): AppConfig => {
+  const result = configSchema.safeParse({
+    env: Bun.env["NODE_ENV"],
+    port: Bun.env["PORT"],
+    host: Bun.env["HOST"],
+    jwt: Bun.env["JWT_SECRET"]
+      ? {
+          secret: Bun.env["JWT_SECRET"],
+          expiresIn: Bun.env["JWT_EXPIRES_IN"],
+          refreshExpiresIn: Bun.env["JWT_REFRESH_EXPIRES_IN"],
+        }
+      : undefined,
+    cors: {
+      origins: Bun.env["CORS_ORIGINS"],
+    },
+    rateLimit: {
+      windowMs: Bun.env["RATE_LIMIT_WINDOW_MS"],
+      maxRequests: Bun.env["RATE_LIMIT_MAX_REQUESTS"],
+    },
+    log: {
+      level: Bun.env["LOG_LEVEL"],
+      format: Bun.env["LOG_FORMAT"],
+    },
+    database: {
+      driver: Bun.env["DATABASE_DRIVER"],
+      url: Bun.env["DATABASE_URL"],
+      path: Bun.env["DATABASE_PATH"],
+    },
+    redis: {
+      enabled: Bun.env["REDIS_ENABLED"],
+      host: Bun.env["REDIS_HOST"],
+      port: Bun.env["REDIS_PORT"],
+      password: Bun.env["REDIS_PASSWORD"],
+      db: Bun.env["REDIS_DB"],
+    },
+    i18n: {
+      defaultLocale: Bun.env["I18N_DEFAULT_LOCALE"],
+      supportedLocales: Bun.env["I18N_SUPPORTED_LOCALES"],
+    },
+    lockout: {
+      maxAttempts: Bun.env["LOCKOUT_MAX_ATTEMPTS"],
+      durationMs: Bun.env["LOCKOUT_DURATION_MS"],
+    },
+    alerting: {
+      webhookUrl: Bun.env["ALERT_WEBHOOK_URL"],
+      timeoutMs: Bun.env["ALERT_TIMEOUT_MS"],
+    },
+    circuitBreaker: {
+      failureThreshold: Bun.env["CB_FAILURE_THRESHOLD"],
+      resetTimeoutMs: Bun.env["CB_RESET_TIMEOUT_MS"],
+      halfOpenSuccessThreshold: Bun.env["CB_HALF_OPEN_SUCCESS_THRESHOLD"],
+    },
+    passwordPolicy: {
+      minLength: Bun.env["PASSWORD_MIN_LENGTH"],
+      requireUppercase: Bun.env["PASSWORD_REQUIRE_UPPERCASE"],
+      requireLowercase: Bun.env["PASSWORD_REQUIRE_LOWERCASE"],
+      requireDigit: Bun.env["PASSWORD_REQUIRE_DIGIT"],
+      requireSpecial: Bun.env["PASSWORD_REQUIRE_SPECIAL"],
+      historyCount: Bun.env["PASSWORD_HISTORY_COUNT"],
+      maxAgeDays: Bun.env["PASSWORD_MAX_AGE_DAYS"],
+    },
+    oauth: {
+      googleClientId: Bun.env["OAUTH_GOOGLE_CLIENT_ID"],
+      googleClientSecret: Bun.env["OAUTH_GOOGLE_CLIENT_SECRET"],
+      githubClientId: Bun.env["OAUTH_GITHUB_CLIENT_ID"],
+      githubClientSecret: Bun.env["OAUTH_GITHUB_CLIENT_SECRET"],
+    },
+  });
+
+  if (!result.success) {
+    const formatted = result.error.flatten();
+    printConfigError(formatted.fieldErrors as Record<string, string[]>);
+    process.exit(1);
+  }
+
+  return result.data;
+};

package/src/infrastructure/config/index.ts

@@ -0,0 +1 @@
+export { type AppConfig, loadConfig } from "./config.js";