@criterionx/server 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomas Maritano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @criterionx/server
+
+HTTP server for Criterion decisions with auto-generated documentation.
+
+> **The server is a delivery mechanism, not a decision engine.**
+
+## Installation
+
+```bash
+npm install @criterionx/server @criterionx/core zod
+```
+
+## Quick Start
+
+```typescript
+import { createServer } from "@criterionx/server";
+import { defineDecision } from "@criterionx/core";
+import { z } from "zod";
+
+const riskDecision = defineDecision({
+  id: "transaction-risk",
+  version: "1.0.0",
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.object({ risk: z.enum(["HIGH", "LOW"]) }),
+  profileSchema: z.object({ threshold: z.number() }),
+  rules: [
+    {
+      id: "high-risk",
+      when: (input, profile) => input.amount > profile.threshold,
+      emit: () => ({ risk: "HIGH" }),
+      explain: (input, profile) =>
+        `Amount ${input.amount} exceeds threshold ${profile.threshold}`,
+    },
+    {
+      id: "low-risk",
+      when: () => true,
+      emit: () => ({ risk: "LOW" }),
+      explain: () => "Amount within acceptable range",
+    },
+  ],
+});
+
+const server = createServer({
+  decisions: [riskDecision],
+  profiles: {
+    "transaction-risk": { threshold: 10000 },
+  },
+});
+
+server.listen(3000);
+// Server running at http://localhost:3000
+// Docs at http://localhost:3000/docs
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Health check |
+| GET | `/docs` | Interactive documentation UI |
+| GET | `/decisions` | List all registered decisions |
+| GET | `/decisions/:id/schema` | JSON Schema for decision |
+| POST | `/decisions/:id` | Evaluate a decision |
+
+## API
+
+### `createServer(options)`
+
+Creates a new Criterion server.
+
+```typescript
+interface ServerOptions<TDecisions> {
+  decisions: TDecisions[];
+  profiles?: Record<string, unknown>;
+  port?: number;
+  cors?: boolean;
+}
+```
+
+### POST `/decisions/:id`
+
+Evaluate a decision with the given input.
+
+**Request:**
+```json
+{
+  "input": { "amount": 15000 },
+  "profile": { "threshold": 10000 }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "OK",
+  "data": { "risk": "HIGH" },
+  "meta": {
+    "decisionId": "transaction-risk",
+    "decisionVersion": "1.0.0",
+    "matchedRule": "high-risk",
+    "explanation": "Amount 15000 exceeds threshold 10000",
+    "evaluatedAt": "2024-12-29T12:00:00.000Z"
+  }
+}
+```
+
+## Design Principles
+
+1. **Server does NOT add decision logic** — only calls `engine.run()`
+2. **Decisions are explicitly registered** — no auto-discovery
+3. **UI cannot invent defaults** — shows exactly what's required
+4. **JSON Schema is primary** — OpenAPI is derived
+
+## Documentation
+
+Full documentation: [https://tomymaritano.github.io/criterionx/](https://tomymaritano.github.io/criterionx/)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { Decision } from '@criterionx/core';
+import { ZodSchema } from 'zod';
+import { Hono } from 'hono';
+
+/**
+ * Server configuration options
+ */
+interface ServerOptions {
+    /** Decisions to expose via HTTP */
+    decisions: Decision<any, any, any>[];
+    /** Default profiles for decisions (keyed by decision ID) */
+    profiles?: Record<string, unknown>;
+    /** Enable CORS (default: true) */
+    cors?: boolean;
+}
+/**
+ * Request body for decision evaluation
+ */
+interface EvaluateRequest {
+    /** Input data for the decision */
+    input: unknown;
+    /** Profile to use (overrides default) */
+    profile?: unknown;
+}
+/**
+ * Decision info for listing
+ */
+interface DecisionInfo {
+    id: string;
+    version: string;
+    description?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * JSON Schema representation
+ */
+interface JsonSchema {
+    $schema?: string;
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: JsonSchema;
+    enum?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Decision schema export
+ */
+interface DecisionSchema {
+    id: string;
+    version: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    profileSchema: JsonSchema;
+}
+
+/**
+ * Convert a Zod schema to JSON Schema
+ */
+declare function toJsonSchema(schema: ZodSchema): JsonSchema;
+/**
+ * Extract JSON Schemas from a decision
+ */
+declare function extractDecisionSchema(decision: Decision<unknown, unknown, unknown>): DecisionSchema;
+/**
+ * Generate OpenAPI-compatible schema for a decision endpoint
+ */
+declare function generateEndpointSchema(decision: Decision<unknown, unknown, unknown>): {
+    requestBody: JsonSchema;
+    response: JsonSchema;
+};
+
+/**
+ * Criterion Server
+ *
+ * Exposes decisions as HTTP endpoints with auto-generated documentation.
+ */
+declare class CriterionServer {
+    private app;
+    private engine;
+    private decisions;
+    private profiles;
+    constructor(options: ServerOptions);
+    private setupRoutes;
+    private generateDocsHtml;
+    /**
+     * Get the Hono app instance (for custom middleware)
+     */
+    get handler(): Hono;
+    /**
+     * Start the server
+     */
+    listen(port?: number): void;
+}
+/**
+ * Create a new Criterion server
+ */
+declare function createServer(options: ServerOptions): CriterionServer;
+
+export { CriterionServer, type DecisionInfo, type DecisionSchema, type EvaluateRequest, type JsonSchema, type ServerOptions, createServer, extractDecisionSchema, generateEndpointSchema, toJsonSchema };

package/dist/index.js

@@ -0,0 +1,389 @@
+// 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)
+  };
+}
+function generateEndpointSchema(decision) {
+  const inputSchema = toJsonSchema(decision.inputSchema);
+  const profileSchema = toJsonSchema(decision.profileSchema);
+  return {
+    requestBody: {
+      type: "object",
+      properties: {
+        input: inputSchema,
+        profile: profileSchema
+      },
+      required: ["input"]
+    },
+    response: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["OK", "NO_MATCH", "INVALID_INPUT", "INVALID_OUTPUT"]
+        },
+        data: toJsonSchema(decision.outputSchema),
+        meta: {
+          type: "object",
+          properties: {
+            decisionId: { type: "string" },
+            decisionVersion: { type: "string" },
+            profileId: { type: "string" },
+            matchedRule: { type: "string" },
+            explanation: { type: "string" },
+            evaluatedAt: { type: "string", format: "date-time" }
+          }
+        }
+      },
+      required: ["status", "data", "meta"]
+    }
+  };
+}
+
+// src/server.ts
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { serve } from "@hono/node-server";
+import { Engine } from "@criterionx/core";
+var CriterionServer = class {
+  app;
+  engine;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  decisions;
+  profiles;
+  constructor(options) {
+    this.app = new Hono();
+    this.engine = new Engine();
+    this.decisions = /* @__PURE__ */ new Map();
+    this.profiles = /* @__PURE__ */ new Map();
+    for (const decision of options.decisions) {
+      this.decisions.set(decision.id, decision);
+    }
+    if (options.profiles) {
+      for (const [id, profile] of Object.entries(options.profiles)) {
+        this.profiles.set(id, profile);
+      }
+    }
+    if (options.cors !== false) {
+      this.app.use("*", cors());
+    }
+    this.setupRoutes();
+  }
+  setupRoutes() {
+    this.app.get("/", (c) => {
+      return c.json({
+        name: "Criterion Server",
+        version: "0.1.0",
+        decisions: this.decisions.size
+      });
+    });
+    this.app.get("/decisions", (c) => {
+      const decisions = [];
+      for (const decision of this.decisions.values()) {
+        decisions.push({
+          id: decision.id,
+          version: decision.version,
+          description: decision.meta?.description,
+          meta: decision.meta
+        });
+      }
+      return c.json({ decisions });
+    });
+    this.app.get("/decisions/:id/schema", (c) => {
+      const id = c.req.param("id");
+      const decision = this.decisions.get(id);
+      if (!decision) {
+        return c.json({ error: `Decision not found: ${id}` }, 404);
+      }
+      const schema = extractDecisionSchema(decision);
+      return c.json(schema);
+    });
+    this.app.get("/decisions/:id/endpoint-schema", (c) => {
+      const id = c.req.param("id");
+      const decision = this.decisions.get(id);
+      if (!decision) {
+        return c.json({ error: `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 decision = this.decisions.get(id);
+      if (!decision) {
+        return c.json({ error: `Decision not found: ${id}` }, 404);
+      }
+      let body;
+      try {
+        body = await c.req.json();
+      } catch {
+        return c.json({ error: "Invalid JSON body" }, 400);
+      }
+      if (body.input === void 0) {
+        return c.json({ error: "Missing 'input' in request body" }, 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}`
+            },
+            400
+          );
+        }
+      }
+      const result = this.engine.run(decision, body.input, { profile });
+      const statusCode = result.status === "OK" ? 200 : 400;
+      return c.json(result, statusCode);
+    });
+    this.app.get("/docs", (c) => {
+      const decisions = Array.from(this.decisions.values()).map((d) => ({
+        id: d.id,
+        version: d.version,
+        description: d.meta?.description
+      }));
+      const html = this.generateDocsHtml(decisions);
+      return c.html(html);
+    });
+  }
+  generateDocsHtml(decisions) {
+    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 Docs</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      line-height: 1.6;
+      color: #1a1a1a;
+      background: #f5f5f5;
+    }
+    .container { max-width: 1200px; margin: 0 auto; padding: 2rem; }
+    header {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      padding: 2rem;
+      margin-bottom: 2rem;
+      border-radius: 8px;
+    }
+    header h1 { font-size: 2rem; margin-bottom: 0.5rem; }
+    header p { opacity: 0.9; }
+    .decisions { display: grid; gap: 1rem; }
+    .decision {
+      background: white;
+      border-radius: 8px;
+      padding: 1.5rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    .decision h2 {
+      font-size: 1.25rem;
+      color: #667eea;
+      margin-bottom: 0.5rem;
+    }
+    .decision .version {
+      font-size: 0.875rem;
+      color: #666;
+      margin-bottom: 1rem;
+    }
+    .decision .description {
+      color: #444;
+      margin-bottom: 1rem;
+    }
+    .endpoint {
+      background: #f8f9fa;
+      border-radius: 4px;
+      padding: 1rem;
+      font-family: monospace;
+      font-size: 0.875rem;
+      margin-bottom: 1rem;
+    }
+    .method {
+      background: #28a745;
+      color: white;
+      padding: 0.25rem 0.5rem;
+      border-radius: 4px;
+      margin-right: 0.5rem;
+    }
+    .playground {
+      margin-top: 1rem;
+      padding-top: 1rem;
+      border-top: 1px solid #eee;
+    }
+    textarea {
+      width: 100%;
+      min-height: 150px;
+      padding: 1rem;
+      font-family: monospace;
+      font-size: 0.875rem;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      margin-bottom: 0.5rem;
+    }
+    button {
+      background: #667eea;
+      color: white;
+      border: none;
+      padding: 0.75rem 1.5rem;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 1rem;
+    }
+    button:hover { background: #5a6fd6; }
+    .result {
+      margin-top: 1rem;
+      padding: 1rem;
+      background: #f8f9fa;
+      border-radius: 4px;
+      font-family: monospace;
+      font-size: 0.875rem;
+      white-space: pre-wrap;
+      display: none;
+    }
+    .result.show { display: block; }
+    .result.error { background: #fff3f3; border: 1px solid #ffcccc; }
+    .result.success { background: #f0fff4; border: 1px solid #9ae6b4; }
+    .links { margin-top: 0.5rem; }
+    .links a {
+      color: #667eea;
+      text-decoration: none;
+      margin-right: 1rem;
+      font-size: 0.875rem;
+    }
+    .links a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>Criterion API</h1>
+      <p>Interactive documentation for registered decisions</p>
+    </header>
+
+    <div class="decisions">
+      ${decisions.map(
+      (d) => `
+        <div class="decision" data-id="${d.id}">
+          <h2>${d.id}</h2>
+          <div class="version">v${d.version}</div>
+          ${d.description ? `<div class="description">${d.description}</div>` : ""}
+          <div class="endpoint">
+            <span class="method">POST</span>
+            /decisions/${d.id}
+          </div>
+          <div class="links">
+            <a href="/decisions/${d.id}/schema" target="_blank">View Schema</a>
+            <a href="/decisions/${d.id}/endpoint-schema" target="_blank">Endpoint Schema</a>
+          </div>
+          <div class="playground">
+            <textarea id="input-${d.id}" placeholder='{"input": {...}, "profile": {...}}'></textarea>
+            <button onclick="evaluate('${d.id}')">Evaluate</button>
+            <div class="result" id="result-${d.id}"></div>
+          </div>
+        </div>
+      `
+    ).join("")}
+    </div>
+  </div>
+
+  <script>
+    // Load schemas for each decision
+    document.querySelectorAll('.decision').forEach(async (el) => {
+      const id = el.dataset.id;
+      const textarea = document.getElementById('input-' + id);
+
+      try {
+        const res = await fetch('/decisions/' + id + '/schema');
+        const schema = await res.json();
+
+        // Generate example from schema
+        const example = {
+          input: generateExample(schema.inputSchema),
+          profile: generateExample(schema.profileSchema)
+        };
+        textarea.value = JSON.stringify(example, null, 2);
+      } catch (e) {
+        console.error('Failed to load schema for', id, e);
+      }
+    });
+
+    function generateExample(schema) {
+      if (!schema || !schema.properties) return {};
+      const obj = {};
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        if (prop.type === 'string') obj[key] = prop.enum ? prop.enum[0] : 'example';
+        else if (prop.type === 'number') obj[key] = 0;
+        else if (prop.type === 'boolean') obj[key] = false;
+        else if (prop.type === 'array') obj[key] = [];
+        else if (prop.type === 'object') obj[key] = generateExample(prop);
+      }
+      return obj;
+    }
+
+    async function evaluate(id) {
+      const textarea = document.getElementById('input-' + id);
+      const resultEl = document.getElementById('result-' + id);
+
+      try {
+        const body = JSON.parse(textarea.value);
+        const res = await fetch('/decisions/' + id, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body)
+        });
+        const data = await res.json();
+
+        resultEl.textContent = JSON.stringify(data, null, 2);
+        resultEl.className = 'result show ' + (data.status === 'OK' ? 'success' : 'error');
+      } catch (e) {
+        resultEl.textContent = 'Error: ' + e.message;
+        resultEl.className = 'result show error';
+      }
+    }
+  </script>
+</body>
+</html>`;
+  }
+  /**
+   * Get the Hono app instance (for custom middleware)
+   */
+  get handler() {
+    return this.app;
+  }
+  /**
+   * Start the server
+   */
+  listen(port = 3e3) {
+    console.log(`Criterion Server starting on port ${port}...`);
+    console.log(`  Decisions: ${this.decisions.size}`);
+    console.log(`  Docs: http://localhost:${port}/docs`);
+    console.log(`  API: http://localhost:${port}/decisions`);
+    serve({
+      fetch: this.app.fetch,
+      port
+    });
+  }
+};
+function createServer(options) {
+  return new CriterionServer(options);
+}
+export {
+  CriterionServer,
+  createServer,
+  extractDecisionSchema,
+  generateEndpointSchema,
+  toJsonSchema
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@criterionx/server",
+  "version": "0.3.0",
+  "description": "HTTP server for Criterion decisions with auto-generated docs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "criterion",
+    "decision-engine",
+    "http-server",
+    "hono",
+    "rest-api",
+    "auto-docs"
+  ],
+  "author": {
+    "name": "Tomas Maritano",
+    "url": "https://github.com/tomymaritano"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/tomymaritano/criterionx/issues"
+  },
+  "homepage": "https://github.com/tomymaritano/criterionx#readme",
+  "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "hono": "^4.6.0",
+    "zod-to-json-schema": "^3.24.0",
+    "@criterionx/core": "0.3.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/dev.ts"
+  }
+}