@criterionx/server 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -1,7 +1,100 @@
-import { Decision } from '@criterionx/core';
-import { ZodSchema } from 'zod';
+import { Decision, Result, JsonSchema } from '@criterionx/core';
+export { DecisionSchema, JsonSchema, extractDecisionSchema, toJsonSchema } from '@criterionx/core';
 import { Hono } from 'hono';
 
+/**
+ * Context passed to hooks
+ */
+interface HookContext {
+    /** ID of the decision being evaluated */
+    decisionId: string;
+    /** Input data for the decision */
+    input: unknown;
+    /** Profile being used */
+    profile: unknown;
+    /** Request ID for tracing (auto-generated) */
+    requestId: string;
+    /** Timestamp when evaluation started */
+    timestamp: Date;
+}
+/**
+ * Hook called before decision evaluation
+ *
+ * Can modify context (input, profile) by returning a modified context.
+ * Return undefined to keep original context.
+ * Throw to abort evaluation with error.
+ */
+type BeforeEvaluateHook = (ctx: HookContext) => Promise<Partial<HookContext> | void> | Partial<HookContext> | void;
+/**
+ * Hook called after decision evaluation
+ *
+ * Receives the evaluation result. Cannot modify the result.
+ * Use for logging, metrics, side effects.
+ */
+type AfterEvaluateHook = (ctx: HookContext, result: Result<unknown>) => Promise<void> | void;
+/**
+ * Hook called when an error occurs during evaluation
+ */
+type OnErrorHook = (ctx: HookContext, error: Error) => Promise<void> | void;
+/**
+ * Middleware hooks configuration
+ */
+interface Hooks {
+    /** Called before decision evaluation */
+    beforeEvaluate?: BeforeEvaluateHook;
+    /** Called after successful evaluation */
+    afterEvaluate?: AfterEvaluateHook;
+    /** Called when an error occurs */
+    onError?: OnErrorHook;
+}
+/**
+ * Metrics configuration options
+ */
+interface MetricsOptions$1 {
+    /** Enable metrics collection (default: false) */
+    enabled?: boolean;
+    /** Endpoint path for metrics (default: /metrics) */
+    endpoint?: string;
+    /** Histogram buckets for latency in seconds */
+    buckets?: number[];
+}
+/**
+ * OpenAPI info object
+ */
+interface OpenAPIInfo {
+    /** API title */
+    title: string;
+    /** API version */
+    version: string;
+    /** API description */
+    description?: string;
+    /** Contact information */
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    /** License information */
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+/**
+ * OpenAPI configuration options
+ */
+interface OpenAPIOptions {
+    /** Enable OpenAPI spec generation (default: false) */
+    enabled?: boolean;
+    /** Endpoint path for OpenAPI spec (default: /openapi.json) */
+    endpoint?: string;
+    /** API info for OpenAPI spec */
+    info?: Partial<OpenAPIInfo>;
+    /** Enable Swagger UI (default: true when openapi is enabled) */
+    swaggerUI?: boolean;
+    /** Swagger UI endpoint (default: /swagger) */
+    swaggerEndpoint?: string;
+}
 /**
  * Server configuration options
  */
@@ -12,6 +105,12 @@ interface ServerOptions {
     profiles?: Record<string, unknown>;
     /** Enable CORS (default: true) */
     cors?: boolean;
+    /** Middleware hooks for evaluation lifecycle */
+    hooks?: Hooks;
+    /** Prometheus metrics configuration */
+    metrics?: MetricsOptions$1;
+    /** OpenAPI spec generation configuration */
+    openapi?: OpenAPIOptions;
 }
 /**
  * Request body for decision evaluation
@@ -32,37 +131,39 @@ interface DecisionInfo {
     meta?: Record<string, unknown>;
 }
 /**
- * JSON Schema representation
+ * Error codes for structured error responses
  */
-interface JsonSchema {
-    $schema?: string;
-    type?: string;
-    properties?: Record<string, JsonSchema>;
-    required?: string[];
-    additionalProperties?: boolean;
-    items?: JsonSchema;
-    enum?: unknown[];
-    [key: string]: unknown;
-}
+type ErrorCode = "DECISION_NOT_FOUND" | "INVALID_JSON" | "MISSING_INPUT" | "MISSING_PROFILE" | "VALIDATION_ERROR" | "EVALUATION_ERROR" | "INTERNAL_ERROR";
 /**
- * Decision schema export
+ * Structured error response
  */
-interface DecisionSchema {
-    id: string;
-    version: string;
-    inputSchema: JsonSchema;
-    outputSchema: JsonSchema;
-    profileSchema: JsonSchema;
+interface ErrorResponse {
+    error: {
+        code: ErrorCode;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    requestId?: string;
+    timestamp: string;
 }
-
 /**
- * Convert a Zod schema to JSON Schema
+ * Health check status
  */
-declare function toJsonSchema(schema: ZodSchema): JsonSchema;
+type HealthStatus = "healthy" | "degraded" | "unhealthy";
 /**
- * Extract JSON Schemas from a decision
+ * Health check response
  */
-declare function extractDecisionSchema(decision: Decision<unknown, unknown, unknown>): DecisionSchema;
+interface HealthResponse {
+    status: HealthStatus;
+    version: string;
+    uptime: number;
+    timestamp: string;
+    checks?: Record<string, {
+        status: HealthStatus;
+        message?: string;
+    }>;
+}
+
 /**
  * Generate OpenAPI-compatible schema for a decision endpoint
  */
@@ -71,6 +172,121 @@ declare function generateEndpointSchema(decision: Decision<unknown, unknown, unk
     response: JsonSchema;
 };
 
+/**
+ * Lightweight metrics collector for Criterion Server
+ *
+ * Exposes metrics in Prometheus format without external dependencies.
+ */
+interface MetricsOptions {
+    /** Enable metrics collection (default: false) */
+    enabled?: boolean;
+    /** Endpoint path for metrics (default: /metrics) */
+    endpoint?: string;
+    /** Histogram buckets for latency in seconds */
+    buckets?: number[];
+}
+interface MetricLabels {
+    [key: string]: string;
+}
+/**
+ * Simple metrics collector that outputs Prometheus format
+ */
+declare class MetricsCollector {
+    private counters;
+    private histograms;
+    private buckets;
+    constructor(options?: MetricsOptions);
+    /**
+     * Increment a counter metric
+     */
+    increment(name: string, labels?: MetricLabels, value?: number): void;
+    /**
+     * Record a value in a histogram metric
+     */
+    observe(name: string, labels: MetricLabels, value: number): void;
+    /**
+     * Get a counter value
+     */
+    getCounter(name: string, labels?: MetricLabels): number;
+    /**
+     * Get histogram stats
+     */
+    getHistogram(name: string, labels: MetricLabels): {
+        sum: number;
+        count: number;
+    } | undefined;
+    /**
+     * Export all metrics in Prometheus format
+     */
+    toPrometheus(): string;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    private findCounter;
+    private findHistogram;
+    private labelsMatch;
+    private formatLabels;
+}
+declare const METRIC_EVALUATIONS_TOTAL = "criterion_evaluations_total";
+declare const METRIC_EVALUATION_DURATION_SECONDS = "criterion_evaluation_duration_seconds";
+declare const METRIC_RULE_MATCHES_TOTAL = "criterion_rule_matches_total";
+
+/**
+ * OpenAPI 3.0 spec generator for Criterion decisions
+ */
+
+/**
+ * OpenAPI 3.0 specification
+ */
+interface OpenAPISpec {
+    openapi: "3.0.0";
+    info: OpenAPIInfo;
+    paths: Record<string, PathItem>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+    };
+}
+interface PathItem {
+    post?: Operation;
+    get?: Operation;
+}
+interface Operation {
+    operationId: string;
+    summary: string;
+    description?: string;
+    tags?: string[];
+    requestBody?: {
+        required: boolean;
+        content: {
+            "application/json": {
+                schema: {
+                    $ref: string;
+                } | JsonSchema;
+            };
+        };
+    };
+    responses: Record<string, Response>;
+}
+interface Response {
+    description: string;
+    content?: {
+        "application/json": {
+            schema: {
+                $ref: string;
+            } | JsonSchema;
+        };
+    };
+}
+/**
+ * Generate OpenAPI spec from decisions
+ */
+declare function generateOpenAPISpec(decisions: Decision<any, any, any>[], info?: Partial<OpenAPIInfo>): OpenAPISpec;
+/**
+ * Generate Swagger UI HTML
+ */
+declare function generateSwaggerUIHtml(specUrl: string): string;
+
 /**
  * Criterion Server
  *
@@ -81,6 +297,12 @@ declare class CriterionServer {
     private engine;
     private decisions;
     private profiles;
+    private hooks;
+    private metricsCollector;
+    private metricsOptions;
+    private openApiOptions;
+    private openApiSpec;
+    private startTime;
     constructor(options: ServerOptions);
     private setupRoutes;
     private generateDocsHtml;
@@ -88,6 +310,10 @@ declare class CriterionServer {
      * Get the Hono app instance (for custom middleware)
      */
     get handler(): Hono;
+    /**
+     * Get the metrics collector (if enabled)
+     */
+    get metrics(): MetricsCollector | null;
     /**
      * Start the server
      */
@@ -98,4 +324,4 @@ declare class CriterionServer {
  */
 declare function createServer(options: ServerOptions): CriterionServer;
 
-export { CriterionServer, type DecisionInfo, type DecisionSchema, type EvaluateRequest, type JsonSchema, type ServerOptions, createServer, extractDecisionSchema, generateEndpointSchema, toJsonSchema };
+export { type AfterEvaluateHook, type BeforeEvaluateHook, CriterionServer, type DecisionInfo, type ErrorCode, type ErrorResponse, type EvaluateRequest, type HealthResponse, type HealthStatus, type HookContext, type Hooks, METRIC_EVALUATIONS_TOTAL, METRIC_EVALUATION_DURATION_SECONDS, METRIC_RULE_MATCHES_TOTAL, MetricsCollector, type MetricsOptions$1 as MetricsOptions, type OnErrorHook, type OpenAPIInfo, type OpenAPIOptions, type OpenAPISpec, type ServerOptions, createServer, generateEndpointSchema, generateOpenAPISpec, generateSwaggerUIHtml };

package/dist/index.js

@@ -1,17 +1,8 @@
 // src/schema.ts
-import { zodToJsonSchema } from "zod-to-json-schema";
-function toJsonSchema(schema) {
-  return zodToJsonSchema(schema, { $refStrategy: "none" });
-}
-function extractDecisionSchema(decision) {
-  return {
-    id: decision.id,
-    version: decision.version,
-    inputSchema: toJsonSchema(decision.inputSchema),
-    outputSchema: toJsonSchema(decision.outputSchema),
-    profileSchema: toJsonSchema(decision.profileSchema)
-  };
-}
+import {
+  toJsonSchema,
+  extractDecisionSchema
+} from "@criterionx/core";
 function generateEndpointSchema(decision) {
   const inputSchema = toJsonSchema(decision.inputSchema);
   const profileSchema = toJsonSchema(decision.profileSchema);
@@ -49,22 +40,462 @@ function generateEndpointSchema(decision) {
   };
 }
 
+// src/metrics.ts
+var MetricsCollector = class {
+  counters = /* @__PURE__ */ new Map();
+  histograms = /* @__PURE__ */ new Map();
+  buckets;
+  constructor(options = {}) {
+    this.buckets = options.buckets ?? [
+      1e-3,
+      5e-3,
+      0.01,
+      0.025,
+      0.05,
+      0.1,
+      0.25,
+      0.5,
+      1,
+      2.5,
+      5,
+      10
+    ];
+  }
+  /**
+   * Increment a counter metric
+   */
+  increment(name, labels = {}, value = 1) {
+    const existing = this.findCounter(name, labels);
+    if (existing) {
+      existing.value += value;
+    } else {
+      if (!this.counters.has(name)) {
+        this.counters.set(name, []);
+      }
+      this.counters.get(name).push({ labels, value });
+    }
+  }
+  /**
+   * Record a value in a histogram metric
+   */
+  observe(name, labels, value) {
+    const existing = this.findHistogram(name, labels);
+    if (existing) {
+      existing.sum += value;
+      existing.count += 1;
+      for (const bucket of this.buckets) {
+        if (value <= bucket) {
+          existing.buckets.set(bucket, (existing.buckets.get(bucket) ?? 0) + 1);
+        }
+      }
+    } else {
+      if (!this.histograms.has(name)) {
+        this.histograms.set(name, []);
+      }
+      const bucketMap = /* @__PURE__ */ new Map();
+      for (const bucket of this.buckets) {
+        bucketMap.set(bucket, value <= bucket ? 1 : 0);
+      }
+      this.histograms.get(name).push({
+        labels,
+        sum: value,
+        count: 1,
+        buckets: bucketMap
+      });
+    }
+  }
+  /**
+   * Get a counter value
+   */
+  getCounter(name, labels = {}) {
+    return this.findCounter(name, labels)?.value ?? 0;
+  }
+  /**
+   * Get histogram stats
+   */
+  getHistogram(name, labels) {
+    const h = this.findHistogram(name, labels);
+    if (!h) return void 0;
+    return { sum: h.sum, count: h.count };
+  }
+  /**
+   * Export all metrics in Prometheus format
+   */
+  toPrometheus() {
+    const lines = [];
+    for (const [name, values] of this.counters) {
+      lines.push(`# HELP ${name} Counter metric`);
+      lines.push(`# TYPE ${name} counter`);
+      for (const v of values) {
+        const labelStr = this.formatLabels(v.labels);
+        lines.push(`${name}${labelStr} ${v.value}`);
+      }
+    }
+    for (const [name, values] of this.histograms) {
+      lines.push(`# HELP ${name} Histogram metric`);
+      lines.push(`# TYPE ${name} histogram`);
+      for (const v of values) {
+        const baseLabels = this.formatLabels(v.labels);
+        let cumulative = 0;
+        for (const bucket of this.buckets) {
+          cumulative += v.buckets.get(bucket) ?? 0;
+          const bucketLabels = this.formatLabels({ ...v.labels, le: String(bucket) });
+          lines.push(`${name}_bucket${bucketLabels} ${cumulative}`);
+        }
+        const infLabels = this.formatLabels({ ...v.labels, le: "+Inf" });
+        lines.push(`${name}_bucket${infLabels} ${v.count}`);
+        lines.push(`${name}_sum${baseLabels} ${v.sum}`);
+        lines.push(`${name}_count${baseLabels} ${v.count}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    this.counters.clear();
+    this.histograms.clear();
+  }
+  findCounter(name, labels) {
+    const values = this.counters.get(name);
+    if (!values) return void 0;
+    return values.find((v) => this.labelsMatch(v.labels, labels));
+  }
+  findHistogram(name, labels) {
+    const values = this.histograms.get(name);
+    if (!values) return void 0;
+    return values.find((v) => this.labelsMatch(v.labels, labels));
+  }
+  labelsMatch(a, b) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((key) => a[key] === b[key]);
+  }
+  formatLabels(labels) {
+    const entries = Object.entries(labels);
+    if (entries.length === 0) return "";
+    const parts = entries.map(([k, v]) => `${k}="${v}"`);
+    return `{${parts.join(",")}}`;
+  }
+};
+var METRIC_EVALUATIONS_TOTAL = "criterion_evaluations_total";
+var METRIC_EVALUATION_DURATION_SECONDS = "criterion_evaluation_duration_seconds";
+var METRIC_RULE_MATCHES_TOTAL = "criterion_rule_matches_total";
+
+// src/openapi.ts
+function toSchemaName(id, suffix) {
+  const pascal = id.split(/[-_]/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return `${pascal}${suffix}`;
+}
+function generateOpenAPISpec(decisions, info = {}) {
+  const paths = {};
+  const schemas = {};
+  schemas["EvaluateRequest"] = {
+    type: "object",
+    properties: {
+      input: { description: "Input data for the decision" },
+      profile: { description: "Profile to use (overrides default)" }
+    },
+    required: ["input"]
+  };
+  schemas["EvaluationResult"] = {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        enum: ["OK", "INVALID_INPUT", "INVALID_OUTPUT", "NO_MATCH"],
+        description: "Evaluation status"
+      },
+      data: {
+        description: "Output data (null if status is not OK)"
+      },
+      meta: {
+        $ref: "#/components/schemas/ResultMeta"
+      }
+    },
+    required: ["status", "data", "meta"]
+  };
+  schemas["ResultMeta"] = {
+    type: "object",
+    properties: {
+      decisionId: { type: "string" },
+      decisionVersion: { type: "string" },
+      profileId: { type: "string" },
+      matchedRule: { type: "string" },
+      explanation: { type: "string" },
+      evaluatedAt: { type: "string", format: "date-time" },
+      evaluatedRules: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            ruleId: { type: "string" },
+            matched: { type: "boolean" },
+            explanation: { type: "string" }
+          }
+        }
+      }
+    }
+  };
+  schemas["ErrorResponse"] = {
+    type: "object",
+    properties: {
+      error: { type: "string", description: "Error message" }
+    },
+    required: ["error"]
+  };
+  for (const decision of decisions) {
+    const decisionSchema = extractDecisionSchema(decision);
+    const inputSchemaName = toSchemaName(decision.id, "Input");
+    const outputSchemaName = toSchemaName(decision.id, "Output");
+    const profileSchemaName = toSchemaName(decision.id, "Profile");
+    const requestSchemaName = toSchemaName(decision.id, "Request");
+    schemas[inputSchemaName] = decisionSchema.inputSchema;
+    schemas[outputSchemaName] = decisionSchema.outputSchema;
+    schemas[profileSchemaName] = decisionSchema.profileSchema;
+    schemas[requestSchemaName] = {
+      type: "object",
+      properties: {
+        input: { $ref: `#/components/schemas/${inputSchemaName}` },
+        profile: { $ref: `#/components/schemas/${profileSchemaName}` }
+      },
+      required: ["input"]
+    };
+    const path = `/decisions/${decision.id}`;
+    const description = decision.meta?.description;
+    paths[path] = {
+      post: {
+        operationId: `evaluate_${decision.id.replace(/-/g, "_")}`,
+        summary: `Evaluate ${decision.id}`,
+        description: description ?? `Evaluate the ${decision.id} decision`,
+        tags: ["decisions"],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${requestSchemaName}` }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Decision evaluated successfully",
+            content: {
+              "application/json": {
+                schema: {
+                  allOf: [
+                    { $ref: "#/components/schemas/EvaluationResult" },
+                    {
+                      type: "object",
+                      properties: {
+                        data: { $ref: `#/components/schemas/${outputSchemaName}` }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            description: "Invalid input or no matching rule",
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/EvaluationResult" }
+              }
+            }
+          },
+          "404": {
+            description: "Decision not found",
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    };
+    paths[`${path}/schema`] = {
+      get: {
+        operationId: `get_${decision.id.replace(/-/g, "_")}_schema`,
+        summary: `Get ${decision.id} schema`,
+        description: `Get JSON Schema for the ${decision.id} decision`,
+        tags: ["schemas"],
+        responses: {
+          "200": {
+            description: "Decision schema",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    version: { type: "string" },
+                    inputSchema: { type: "object" },
+                    outputSchema: { type: "object" },
+                    profileSchema: { type: "object" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+  paths["/"] = {
+    get: {
+      operationId: "health_check",
+      summary: "Health check",
+      tags: ["system"],
+      responses: {
+        "200": {
+          description: "Server status",
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                  version: { type: "string" },
+                  decisions: { type: "integer" },
+                  metrics: { type: "boolean" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  };
+  paths["/decisions"] = {
+    get: {
+      operationId: "list_decisions",
+      summary: "List all decisions",
+      tags: ["decisions"],
+      responses: {
+        "200": {
+          description: "List of registered decisions",
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  decisions: {
+                    type: "array",
+                    items: {
+                      type: "object",
+                      properties: {
+                        id: { type: "string" },
+                        version: { type: "string" },
+                        description: { type: "string" },
+                        meta: { type: "object" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  };
+  return {
+    openapi: "3.0.0",
+    info: {
+      title: info.title ?? "Criterion Decision API",
+      version: info.version ?? "1.0.0",
+      description: info.description ?? "Auto-generated API for Criterion decisions",
+      ...info.contact && { contact: info.contact },
+      ...info.license && { license: info.license }
+    },
+    paths,
+    components: {
+      schemas
+    }
+  };
+}
+function generateSwaggerUIHtml(specUrl) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Criterion API - Swagger UI</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <style>
+    body { margin: 0; padding: 0; }
+    .swagger-ui .topbar { display: none; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    window.onload = function() {
+      SwaggerUIBundle({
+        url: "${specUrl}",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+        layout: "BaseLayout"
+      });
+    };
+  </script>
+</body>
+</html>`;
+}
+
 // src/server.ts
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { serve } from "@hono/node-server";
 import { Engine } from "@criterionx/core";
+var SERVER_VERSION = "0.3.2";
+function generateRequestId() {
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
+}
+function createErrorResponse(code, message, requestId, details) {
+  return {
+    error: {
+      code,
+      message,
+      ...details && { details }
+    },
+    ...requestId && { requestId },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
 var CriterionServer = class {
   app;
   engine;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   decisions;
   profiles;
+  hooks;
+  metricsCollector = null;
+  metricsOptions;
+  openApiOptions;
+  openApiSpec = null;
+  startTime;
   constructor(options) {
     this.app = new Hono();
     this.engine = new Engine();
     this.decisions = /* @__PURE__ */ new Map();
     this.profiles = /* @__PURE__ */ new Map();
+    this.hooks = options.hooks ?? {};
+    this.metricsOptions = options.metrics ?? {};
+    this.openApiOptions = options.openapi ?? {};
+    this.startTime = /* @__PURE__ */ new Date();
+    if (this.metricsOptions.enabled) {
+      this.metricsCollector = new MetricsCollector(this.metricsOptions);
+    }
     for (const decision of options.decisions) {
       this.decisions.set(decision.id, decision);
     }
@@ -73,6 +504,12 @@ var CriterionServer = class {
         this.profiles.set(id, profile);
       }
     }
+    if (this.openApiOptions.enabled) {
+      this.openApiSpec = generateOpenAPISpec(
+        options.decisions,
+        this.openApiOptions.info
+      );
+    }
     if (options.cors !== false) {
       this.app.use("*", cors());
     }
@@ -82,10 +519,52 @@ var CriterionServer = class {
     this.app.get("/", (c) => {
       return c.json({
         name: "Criterion Server",
-        version: "0.1.0",
-        decisions: this.decisions.size
+        version: SERVER_VERSION,
+        decisions: this.decisions.size,
+        docs: "/docs",
+        health: "/health"
       });
     });
+    this.app.get("/health", (c) => {
+      const uptime = Math.floor((Date.now() - this.startTime.getTime()) / 1e3);
+      const response = {
+        status: "healthy",
+        version: SERVER_VERSION,
+        uptime,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        checks: {
+          decisions: {
+            status: this.decisions.size > 0 ? "healthy" : "degraded",
+            message: `${this.decisions.size} decision(s) registered`
+          },
+          engine: {
+            status: "healthy",
+            message: "Engine operational"
+          }
+        }
+      };
+      return c.json(response);
+    });
+    if (this.metricsCollector) {
+      const endpoint = this.metricsOptions.endpoint ?? "/metrics";
+      this.app.get(endpoint, (c) => {
+        c.header("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+        return c.text(this.metricsCollector.toPrometheus());
+      });
+    }
+    if (this.openApiSpec) {
+      const specEndpoint = this.openApiOptions.endpoint ?? "/openapi.json";
+      this.app.get(specEndpoint, (c) => {
+        return c.json(this.openApiSpec);
+      });
+      if (this.openApiOptions.swaggerUI !== false) {
+        const swaggerEndpoint = this.openApiOptions.swaggerEndpoint ?? "/swagger";
+        this.app.get(swaggerEndpoint, (c) => {
+          const html = generateSwaggerUIHtml(specEndpoint);
+          return c.html(html);
+        });
+      }
+    }
     this.app.get("/decisions", (c) => {
       const decisions = [];
       for (const decision of this.decisions.values()) {
@@ -102,7 +581,10 @@ var CriterionServer = class {
       const id = c.req.param("id");
       const decision = this.decisions.get(id);
       if (!decision) {
-        return c.json({ error: `Decision not found: ${id}` }, 404);
+        return c.json(
+          createErrorResponse("DECISION_NOT_FOUND", `Decision not found: ${id}`),
+          404
+        );
       }
       const schema = extractDecisionSchema(decision);
       return c.json(schema);
@@ -111,41 +593,115 @@ var CriterionServer = class {
       const id = c.req.param("id");
       const decision = this.decisions.get(id);
       if (!decision) {
-        return c.json({ error: `Decision not found: ${id}` }, 404);
+        return c.json(
+          createErrorResponse("DECISION_NOT_FOUND", `Decision not found: ${id}`),
+          404
+        );
       }
       const schema = generateEndpointSchema(decision);
       return c.json(schema);
     });
     this.app.post("/decisions/:id", async (c) => {
       const id = c.req.param("id");
+      const requestId = generateRequestId();
       const decision = this.decisions.get(id);
       if (!decision) {
-        return c.json({ error: `Decision not found: ${id}` }, 404);
+        return c.json(
+          createErrorResponse("DECISION_NOT_FOUND", `Decision not found: ${id}`, requestId),
+          404
+        );
       }
       let body;
       try {
         body = await c.req.json();
       } catch {
-        return c.json({ error: "Invalid JSON body" }, 400);
+        return c.json(
+          createErrorResponse("INVALID_JSON", "Invalid JSON body", requestId),
+          400
+        );
       }
       if (body.input === void 0) {
-        return c.json({ error: "Missing 'input' in request body" }, 400);
+        return c.json(
+          createErrorResponse("MISSING_INPUT", "Missing 'input' in request body", requestId),
+          400
+        );
       }
       let profile = body.profile;
       if (!profile) {
         profile = this.profiles.get(id);
         if (!profile) {
           return c.json(
-            {
-              error: `No profile provided and no default profile for decision: ${id}`
-            },
+            createErrorResponse(
+              "MISSING_PROFILE",
+              `No profile provided and no default profile for decision: ${id}`,
+              requestId
+            ),
             400
           );
         }
       }
-      const result = this.engine.run(decision, body.input, { profile });
-      const statusCode = result.status === "OK" ? 200 : 400;
-      return c.json(result, statusCode);
+      let ctx = {
+        decisionId: id,
+        input: body.input,
+        profile,
+        requestId,
+        timestamp: /* @__PURE__ */ new Date()
+      };
+      const startTime = performance.now();
+      try {
+        if (this.hooks.beforeEvaluate) {
+          const modified = await this.hooks.beforeEvaluate(ctx);
+          if (modified) {
+            ctx = { ...ctx, ...modified };
+          }
+        }
+        const result = this.engine.run(decision, ctx.input, {
+          profile: ctx.profile
+        });
+        if (this.metricsCollector) {
+          const durationSeconds = (performance.now() - startTime) / 1e3;
+          this.metricsCollector.increment(METRIC_EVALUATIONS_TOTAL, {
+            decision_id: id,
+            status: result.status
+          });
+          this.metricsCollector.observe(
+            METRIC_EVALUATION_DURATION_SECONDS,
+            { decision_id: id },
+            durationSeconds
+          );
+          if (result.meta.matchedRule) {
+            this.metricsCollector.increment(METRIC_RULE_MATCHES_TOTAL, {
+              decision_id: id,
+              rule_id: result.meta.matchedRule
+            });
+          }
+        }
+        if (this.hooks.afterEvaluate) {
+          await this.hooks.afterEvaluate(ctx, result);
+        }
+        const statusCode = result.status === "OK" ? 200 : 400;
+        return c.json(result, statusCode);
+      } catch (error) {
+        if (this.metricsCollector) {
+          this.metricsCollector.increment(METRIC_EVALUATIONS_TOTAL, {
+            decision_id: id,
+            status: "ERROR"
+          });
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (this.hooks.onError) {
+          await this.hooks.onError(ctx, err);
+        }
+        return c.json(
+          createErrorResponse(
+            "EVALUATION_ERROR",
+            err.message,
+            requestId,
+            { decisionId: id }
+          ),
+          500
+        );
+      }
     });
     this.app.get("/docs", (c) => {
       const decisions = Array.from(this.decisions.values()).map((d) => ({
@@ -363,6 +919,12 @@ var CriterionServer = class {
   get handler() {
     return this.app;
   }
+  /**
+   * Get the metrics collector (if enabled)
+   */
+  get metrics() {
+    return this.metricsCollector;
+  }
   /**
    * Start the server
    */
@@ -371,6 +933,18 @@ var CriterionServer = class {
     console.log(`  Decisions: ${this.decisions.size}`);
     console.log(`  Docs: http://localhost:${port}/docs`);
     console.log(`  API: http://localhost:${port}/decisions`);
+    if (this.metricsCollector) {
+      const endpoint = this.metricsOptions.endpoint ?? "/metrics";
+      console.log(`  Metrics: http://localhost:${port}${endpoint}`);
+    }
+    if (this.openApiSpec) {
+      const specEndpoint = this.openApiOptions.endpoint ?? "/openapi.json";
+      console.log(`  OpenAPI: http://localhost:${port}${specEndpoint}`);
+      if (this.openApiOptions.swaggerUI !== false) {
+        const swaggerEndpoint = this.openApiOptions.swaggerEndpoint ?? "/swagger";
+        console.log(`  Swagger: http://localhost:${port}${swaggerEndpoint}`);
+      }
+    }
     serve({
       fetch: this.app.fetch,
       port
@@ -382,8 +956,14 @@ function createServer(options) {
 }
 export {
   CriterionServer,
+  METRIC_EVALUATIONS_TOTAL,
+  METRIC_EVALUATION_DURATION_SECONDS,
+  METRIC_RULE_MATCHES_TOTAL,
+  MetricsCollector,
   createServer,
   extractDecisionSchema,
   generateEndpointSchema,
+  generateOpenAPISpec,
+  generateSwaggerUIHtml,
   toJsonSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criterionx/server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "HTTP server for Criterion decisions with auto-generated docs",
   "type": "module",
   "main": "dist/index.js",
@@ -42,17 +42,17 @@
     "@hono/node-server": "^1.13.0",
     "hono": "^4.6.0",
     "zod-to-json-schema": "^3.24.0",
-    "@criterionx/core": "0.3.0"
+    "@criterionx/core": "0.3.2"
   },
   "peerDependencies": {
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.0.3",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
-    "vitest": "^2.0.0",
+    "vitest": "^4.0.16",
     "zod": "^3.22.0"
   },
   "engines": {