@enderworld/onlyapi 1.5.1

package/src/infrastructure/index.ts

@@ -0,0 +1,58 @@
+export { loadConfig, type AppConfig } from "./config/index.js";
+export { createLogger } from "./logging/index.js";
+export {
+  createPasswordHasher,
+  createTokenService,
+  createInMemoryTokenBlacklist,
+  createInMemoryAccountLockout,
+  createTotpService,
+  createPasswordPolicy,
+} from "./security/index.js";
+export {
+  createInMemoryUserRepository,
+  createSqliteUserRepository,
+  createSqliteTokenBlacklist,
+  createSqliteAccountLockout,
+  createSqliteAuditLog,
+  createSqliteVerificationTokenRepo,
+  createSqliteRefreshTokenStore,
+  createSqliteApiKeyRepository,
+  createSqlitePasswordHistory,
+  createSqliteOAuthAccountRepo,
+  migrateUp,
+  migrateDown,
+} from "./database/index.js";
+export { createMetricsCollector } from "./metrics/index.js";
+export {
+  createCircuitBreaker,
+  CircuitBreakerOpenError,
+  createRetryPolicy,
+} from "./resilience/index.js";
+export { createWebhookAlertSink, createNoopAlertSink } from "./alerting/index.js";
+export {
+  resolveTraceContext,
+  formatTraceparent,
+  type TraceContext,
+} from "./tracing/index.js";
+export { createGoogleOAuthProvider, createGitHubOAuthProvider } from "./oauth/index.js";
+export {
+  createEventBus,
+  createDomainEventFactory,
+  createWebhookDispatcher,
+} from "./events/index.js";
+export { createInMemoryWebhookRegistry } from "./events/in-memory-webhook-registry.js";
+export { createInMemoryJobQueue } from "./jobs/index.js";
+export {
+  createPgUserRepository,
+  createPgTokenBlacklist,
+  createPgAccountLockout,
+  createPgAuditLog,
+  createPgVerificationTokenRepo,
+  createPgRefreshTokenStore,
+  createPgApiKeyRepository,
+  createPgPasswordHistory,
+  createPgOAuthAccountRepo,
+  pgMigrateUp,
+  pgMigrateDown,
+} from "./database/index.js";
+export { createInMemoryCache, createRedisCache } from "./cache/index.js";

package/src/infrastructure/jobs/index.ts

@@ -0,0 +1 @@
+export { createInMemoryJobQueue } from "./job-queue.js";

package/src/infrastructure/jobs/job-queue.ts

@@ -0,0 +1,185 @@
+/**
+ * In-memory background job queue with retry and exponential backoff.
+ *
+ * Uses a polling loop with configurable interval. For production,
+ * swap with a Redis/SQLite-backed adapter.
+ */
+
+import type { AppError } from "../../core/errors/app-error.js";
+import { internal } from "../../core/errors/app-error.js";
+import {
+  type Job,
+  type JobHandler,
+  type JobQueue,
+  type JobQueueStats,
+  JobStatus,
+  type SubmitJobOptions,
+} from "../../core/ports/job-queue.js";
+import type { Logger } from "../../core/ports/logger.js";
+import type { Result } from "../../core/types/result.js";
+import { err, ok } from "../../core/types/result.js";
+import { generateId } from "../../shared/utils/id.js";
+
+interface JobQueueDeps {
+  readonly logger: Logger;
+  /** Polling interval in ms (default: 1000) */
+  readonly pollIntervalMs?: number | undefined;
+}
+
+export const createInMemoryJobQueue = (deps: JobQueueDeps): JobQueue => {
+  const { logger } = deps;
+  const pollIntervalMs = deps.pollIntervalMs ?? 1_000;
+
+  const jobs = new Map<string, Job>();
+  const handlers = new Map<string, JobHandler>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let running = false;
+
+  const updateJob = (id: string, updates: Partial<Job>): void => {
+    const job = jobs.get(id);
+    if (job) {
+      jobs.set(id, { ...job, ...updates, updatedAt: new Date().toISOString() } as Job);
+    }
+  };
+
+  const processJob = async (job: Job): Promise<void> => {
+    const handler = handlers.get(job.type);
+    if (!handler) {
+      logger.warn("No handler registered for job type", { type: job.type, jobId: job.id });
+      updateJob(job.id, { status: JobStatus.DEAD, lastError: `No handler for type: ${job.type}` });
+      return;
+    }
+
+    updateJob(job.id, { status: JobStatus.RUNNING, attempts: job.attempts + 1 });
+
+    try {
+      await handler(job.payload);
+      updateJob(job.id, { status: JobStatus.COMPLETED });
+      logger.debug("Job completed", { jobId: job.id, type: job.type });
+    } catch (e: unknown) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      const newAttempts = job.attempts + 1;
+
+      if (newAttempts >= job.maxRetries) {
+        updateJob(job.id, { status: JobStatus.DEAD, lastError: errorMsg });
+        logger.error("Job failed permanently", {
+          jobId: job.id,
+          type: job.type,
+          attempts: newAttempts,
+          error: errorMsg,
+        });
+      } else {
+        // Exponential backoff: 1s, 2s, 4s, 8s, ... capped at 60s
+        const backoffMs = Math.min(1_000 * 2 ** newAttempts, 60_000);
+        const runAt = new Date(Date.now() + backoffMs).toISOString();
+        updateJob(job.id, {
+          status: JobStatus.PENDING,
+          lastError: errorMsg,
+          runAt,
+        });
+        logger.warn("Job failed, retrying", {
+          jobId: job.id,
+          type: job.type,
+          attempts: newAttempts,
+          nextRunAt: runAt,
+          error: errorMsg,
+        });
+      }
+    }
+  };
+
+  const poll = (): void => {
+    const now = new Date().toISOString();
+    for (const job of jobs.values()) {
+      if (job.status === JobStatus.PENDING && job.runAt <= now) {
+        // Fire and forget — errors are handled inside processJob
+        processJob(job);
+      }
+    }
+  };
+
+  return {
+    submit(options: SubmitJobOptions): Result<Job, AppError> {
+      try {
+        const now = new Date();
+        const runAt = options.delayMs
+          ? new Date(now.getTime() + options.delayMs).toISOString()
+          : now.toISOString();
+
+        const job: Job = {
+          id: generateId(),
+          type: options.type,
+          payload: options.payload,
+          status: JobStatus.PENDING,
+          attempts: 0,
+          maxRetries: options.maxRetries ?? 3,
+          runAt,
+          createdAt: now.toISOString(),
+          updatedAt: now.toISOString(),
+        };
+
+        jobs.set(job.id, job);
+        logger.debug("Job submitted", { jobId: job.id, type: job.type, runAt });
+        return ok(job);
+      } catch (e: unknown) {
+        return err(internal(e instanceof Error ? e.message : "Failed to submit job"));
+      }
+    },
+
+    registerHandler(type: string, handler: JobHandler): void {
+      handlers.set(type, handler);
+      logger.debug("Job handler registered", { type });
+    },
+
+    start(): void {
+      if (running) return;
+      running = true;
+      timer = setInterval(poll, pollIntervalMs);
+      logger.info("Job queue started", { pollIntervalMs });
+    },
+
+    stop(): void {
+      if (!running) return;
+      running = false;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      logger.info("Job queue stopped");
+    },
+
+    getJob(id: string): Result<Job | null, AppError> {
+      return ok(jobs.get(id) ?? null);
+    },
+
+    stats(): Result<JobQueueStats, AppError> {
+      let pending = 0;
+      let jobRunning = 0;
+      let completed = 0;
+      let failed = 0;
+      let dead = 0;
+
+      for (const job of jobs.values()) {
+        switch (job.status) {
+          case JobStatus.PENDING:
+            pending++;
+            break;
+          case JobStatus.RUNNING:
+            jobRunning++;
+            break;
+          case JobStatus.COMPLETED:
+            completed++;
+            break;
+          case JobStatus.FAILED:
+            failed++;
+            break;
+          case JobStatus.DEAD:
+            dead++;
+            break;
+        }
+      }
+
+      return ok({ pending, running: jobRunning, completed, failed, dead });
+    },
+  };
+};

package/src/infrastructure/logging/index.ts

@@ -0,0 +1 @@
+export { createLogger, type LogFormat } from "./logger.js";

package/src/infrastructure/logging/logger.ts

@@ -0,0 +1,63 @@
+import type { LogLevel, Logger } from "../../core/ports/logger.js";
+import { formatLogEntry } from "../../shared/log-format.js";
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+};
+
+export type LogFormat = "pretty" | "json";
+
+/**
+ * Format a log entry as structured JSON (for Datadog, ELK, CloudWatch, etc.).
+ */
+const formatJsonEntry = (level: LogLevel, msg: string, meta: Record<string, unknown>): string => {
+  const entry: Record<string, unknown> = {
+    level,
+    msg,
+    time: new Date().toISOString(),
+    ...meta,
+  };
+  return `${JSON.stringify(entry)}\n`;
+};
+
+/**
+ * Logger — zero dependencies.
+ * Supports two modes:
+ * - "pretty": ANSI-colored human-readable output (default, for development)
+ * - "json": structured JSON lines (for production log aggregators)
+ */
+export const createLogger = (
+  minLevel: LogLevel = "info",
+  bindings: Record<string, unknown> = {},
+  format: LogFormat = "pretty",
+): Logger => {
+  const minPriority = LEVEL_PRIORITY[minLevel];
+
+  const formatter = format === "json" ? formatJsonEntry : formatLogEntry;
+
+  const write = (level: LogLevel, msg: string, meta?: Record<string, unknown>): void => {
+    if (LEVEL_PRIORITY[level] < minPriority) return;
+
+    const allMeta = { ...bindings, ...meta };
+    const line = formatter(level, msg, allMeta);
+
+    if (LEVEL_PRIORITY[level] >= LEVEL_PRIORITY.warn) {
+      process.stderr.write(line);
+    } else {
+      process.stdout.write(line);
+    }
+  };
+
+  return {
+    debug: (msg, meta) => write("debug", msg, meta),
+    info: (msg, meta) => write("info", msg, meta),
+    warn: (msg, meta) => write("warn", msg, meta),
+    error: (msg, meta) => write("error", msg, meta),
+    fatal: (msg, meta) => write("fatal", msg, meta),
+    child: (extra) => createLogger(minLevel, { ...bindings, ...extra }, format),
+  };
+};

package/src/infrastructure/metrics/index.ts

@@ -0,0 +1 @@
+export { createMetricsCollector } from "./prometheus.js";

package/src/infrastructure/metrics/prometheus.ts

@@ -0,0 +1,231 @@
+/**
+ * Prometheus-compatible metrics collector — zero dependencies.
+ *
+ * Implements counters, histograms, and gauges with label support.
+ * Serializes to Prometheus text exposition format (v0.0.4).
+ */
+
+import type {
+  Counter,
+  Gauge,
+  Histogram,
+  HistogramSnapshot,
+  MetricsCollector,
+} from "../../core/ports/metrics.js";
+
+// ── Label key serialization ──
+
+const labelKey = (labels?: Record<string, string>): string => {
+  if (!labels) return "";
+  const entries = Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : 1));
+  if (entries.length === 0) return "";
+  return entries.map(([k, v]) => `${k}="${v}"`).join(",");
+};
+
+const formatLabels = (key: string): string => (key ? `{${key}}` : "");
+
+// ── Counter implementation ──
+
+const createCounter = (name: string, help: string): Counter & { serialize(): string } => {
+  const values = new Map<string, number>();
+
+  return {
+    inc(labels?: Record<string, string>, value = 1) {
+      const key = labelKey(labels);
+      values.set(key, (values.get(key) ?? 0) + value);
+    },
+    get(labels?: Record<string, string>): number {
+      return values.get(labelKey(labels)) ?? 0;
+    },
+    serialize(): string {
+      const lines: string[] = [];
+      lines.push(`# HELP ${name} ${help}`);
+      lines.push(`# TYPE ${name} counter`);
+      for (const [key, value] of values) {
+        lines.push(`${name}${formatLabels(key)} ${value}`);
+      }
+      // If no values recorded, emit a zero line
+      if (values.size === 0) {
+        lines.push(`${name} 0`);
+      }
+      return lines.join("\n");
+    },
+  };
+};
+
+// ── Histogram implementation ──
+
+/** Default Prometheus-style buckets (in ms for latency) */
+const DEFAULT_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+interface HistogramData {
+  count: number;
+  sum: number;
+  buckets: Map<number, number>;
+}
+
+const createHistogram = (
+  name: string,
+  help: string,
+  buckets: readonly number[] = DEFAULT_BUCKETS,
+): Histogram & { serialize(): string } => {
+  const data = new Map<string, HistogramData>();
+
+  const getOrCreate = (key: string): HistogramData => {
+    let entry = data.get(key);
+    if (!entry) {
+      entry = {
+        count: 0,
+        sum: 0,
+        buckets: new Map(buckets.map((b) => [b, 0])),
+      };
+      data.set(key, entry);
+    }
+    return entry;
+  };
+
+  return {
+    observe(value: number, labels?: Record<string, string>) {
+      const key = labelKey(labels);
+      const entry = getOrCreate(key);
+      entry.count++;
+      entry.sum += value;
+      for (const bound of buckets) {
+        if (value <= bound) {
+          entry.buckets.set(bound, (entry.buckets.get(bound) ?? 0) + 1);
+        }
+      }
+    },
+    get(labels?: Record<string, string>): HistogramSnapshot | undefined {
+      const entry = data.get(labelKey(labels));
+      if (!entry) return undefined;
+      return {
+        count: entry.count,
+        sum: entry.sum,
+        buckets: new Map(entry.buckets),
+      };
+    },
+    serialize(): string {
+      const lines: string[] = [];
+      lines.push(`# HELP ${name} ${help}`);
+      lines.push(`# TYPE ${name} histogram`);
+
+      for (const [key, entry] of data) {
+        const lbl = key ? `,${key}` : "";
+        for (const bound of buckets) {
+          const bucketCount = entry.buckets.get(bound) ?? 0;
+          lines.push(`${name}_bucket{le="${bound}"${lbl}} ${bucketCount}`);
+        }
+        lines.push(`${name}_bucket{le="+Inf"${lbl}} ${entry.count}`);
+        lines.push(`${name}_sum${formatLabels(key)} ${entry.sum}`);
+        lines.push(`${name}_count${formatLabels(key)} ${entry.count}`);
+      }
+
+      if (data.size === 0) {
+        // Emit empty buckets
+        for (const bound of buckets) {
+          lines.push(`${name}_bucket{le="${bound}"} 0`);
+        }
+        lines.push(`${name}_bucket{le="+Inf"} 0`);
+        lines.push(`${name}_sum 0`);
+        lines.push(`${name}_count 0`);
+      }
+
+      return lines.join("\n");
+    },
+  };
+};
+
+// ── Gauge implementation ──
+
+const createGauge = (name: string, help: string): Gauge & { serialize(): string } => {
+  const values = new Map<string, number>();
+
+  return {
+    set(value: number, labels?: Record<string, string>) {
+      values.set(labelKey(labels), value);
+    },
+    inc(labels?: Record<string, string>, value = 1) {
+      const key = labelKey(labels);
+      values.set(key, (values.get(key) ?? 0) + value);
+    },
+    dec(labels?: Record<string, string>, value = 1) {
+      const key = labelKey(labels);
+      values.set(key, (values.get(key) ?? 0) - value);
+    },
+    get(labels?: Record<string, string>): number {
+      return values.get(labelKey(labels)) ?? 0;
+    },
+    serialize(): string {
+      const lines: string[] = [];
+      lines.push(`# HELP ${name} ${help}`);
+      lines.push(`# TYPE ${name} gauge`);
+      for (const [key, value] of values) {
+        lines.push(`${name}${formatLabels(key)} ${value}`);
+      }
+      if (values.size === 0) {
+        lines.push(`${name} 0`);
+      }
+      return lines.join("\n");
+    },
+  };
+};
+
+// ── Metrics collector factory ──
+
+export const createMetricsCollector = (): MetricsCollector => {
+  const httpRequestsTotal = createCounter("http_requests_total", "Total number of HTTP requests");
+  const httpRequestDurationMs = createHistogram(
+    "http_request_duration_ms",
+    "HTTP request duration in milliseconds",
+  );
+  const httpActiveConnections = createGauge(
+    "http_active_connections",
+    "Number of currently active HTTP connections",
+  );
+  const httpErrorsTotal = createCounter(
+    "http_errors_total",
+    "Total number of HTTP error responses (4xx + 5xx)",
+  );
+  const circuitBreakerState = createGauge(
+    "circuit_breaker_state",
+    "Circuit breaker state (0=closed, 1=half_open, 2=open)",
+  );
+  const alertsSentTotal = createCounter(
+    "alerts_sent_total",
+    "Total number of alert notifications sent",
+  );
+
+  return {
+    httpRequestsTotal,
+    httpRequestDurationMs,
+    httpActiveConnections,
+    httpErrorsTotal,
+    circuitBreakerState,
+    alertsSentTotal,
+
+    serialize(): string {
+      const sections = [
+        httpRequestsTotal.serialize(),
+        httpRequestDurationMs.serialize(),
+        httpActiveConnections.serialize(),
+        httpErrorsTotal.serialize(),
+        circuitBreakerState.serialize(),
+        alertsSentTotal.serialize(),
+      ];
+      return `${sections.join("\n\n")}\n`;
+    },
+
+    reset(): void {
+      // Re-create would be cleanest but we just reset the underlying maps
+      // For simplicity, we expose reset through the collector
+      const collector = createMetricsCollector();
+      Object.assign(httpRequestsTotal, collector.httpRequestsTotal);
+      Object.assign(httpRequestDurationMs, collector.httpRequestDurationMs);
+      Object.assign(httpActiveConnections, collector.httpActiveConnections);
+      Object.assign(httpErrorsTotal, collector.httpErrorsTotal);
+      Object.assign(circuitBreakerState, collector.circuitBreakerState);
+      Object.assign(alertsSentTotal, collector.alertsSentTotal);
+    },
+  };
+};

package/src/infrastructure/oauth/github.ts

@@ -0,0 +1,116 @@
+import { type AppError, internal, unauthorized } from "../../core/errors/app-error.js";
+import type { OAuthProvider, OAuthUserInfo } from "../../core/ports/oauth.js";
+import { type Result, err, ok } from "../../core/types/result.js";
+
+/**
+ * GitHub OAuth2 provider adapter.
+ * Uses GitHub's OAuth App endpoints for authorization code flow.
+ * Zero external dependencies — uses native fetch.
+ */
+
+interface GitHubOAuthConfig {
+  readonly clientId: string;
+  readonly clientSecret: string;
+}
+
+export const createGitHubOAuthProvider = (config: GitHubOAuthConfig): OAuthProvider => ({
+  name: "github",
+
+  getAuthorizationUrl(state: string, redirectUri: string): string {
+    const params = new URLSearchParams({
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: "user:email",
+      state,
+    });
+    return `https://github.com/login/oauth/authorize?${params.toString()}`;
+  },
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: OAuth code exchange is inherently complex
+  async exchangeCode(code: string, redirectUri: string): Promise<Result<OAuthUserInfo, AppError>> {
+    try {
+      // Exchange authorization code for access token
+      const tokenRes = await fetch("https://github.com/login/oauth/access_token", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+          code,
+          redirect_uri: redirectUri,
+        }),
+      });
+
+      if (!tokenRes.ok) {
+        return err(unauthorized("Failed to exchange authorization code with GitHub"));
+      }
+
+      const tokenData = (await tokenRes.json()) as {
+        access_token?: string;
+        error?: string;
+      };
+      if (tokenData.error || !tokenData.access_token) {
+        return err(unauthorized(tokenData.error ?? "No access token in GitHub response"));
+      }
+
+      // Fetch user info
+      const userRes = await fetch("https://api.github.com/user", {
+        headers: {
+          Authorization: `Bearer ${tokenData.access_token}`,
+          Accept: "application/vnd.github+json",
+          "User-Agent": "onlyApi",
+        },
+      });
+
+      if (!userRes.ok) {
+        return err(unauthorized("Failed to fetch GitHub user info"));
+      }
+
+      const userData = (await userRes.json()) as {
+        id?: number;
+        login?: string;
+        name?: string;
+      };
+
+      if (!userData.id) {
+        return err(unauthorized("Incomplete GitHub user info"));
+      }
+
+      // Fetch primary email (may not be public)
+      let email: string | undefined;
+      const emailRes = await fetch("https://api.github.com/user/emails", {
+        headers: {
+          Authorization: `Bearer ${tokenData.access_token}`,
+          Accept: "application/vnd.github+json",
+          "User-Agent": "onlyApi",
+        },
+      });
+
+      if (emailRes.ok) {
+        const emails = (await emailRes.json()) as Array<{
+          email: string;
+          primary: boolean;
+          verified: boolean;
+        }>;
+        const primary = emails.find((e) => e.primary && e.verified);
+        email = primary?.email;
+      }
+
+      if (!email) {
+        return err(unauthorized("No verified email found on GitHub account"));
+      }
+
+      const displayName = userData.name ?? userData.login;
+      return ok({
+        providerId: String(userData.id),
+        email,
+        ...(displayName ? { name: displayName } : {}),
+      });
+    } catch (e: unknown) {
+      return err(internal("GitHub OAuth exchange failed", e));
+    }
+  },
+});