@run-iq/server

HTTP REST server for the Parametric Policy Engine (PPE). Wraps @run-iq/core behind a Fastify API for polyglot and non-Node integrations.

Installation

npm install @run-iq/server

Quick start

import { start } from '@run-iq/server';
import { FiscalPlugin } from '@run-iq/plugin-fiscal';
import { JsonLogicEvaluator } from '@run-iq/dsl-jsonlogic';

await start({
  port: 3000,
  plugins: [new FiscalPlugin()],
  dsls: [new JsonLogicEvaluator()],
  strict: false,
});

API

GET /health

{ "status": "ok", "engine": "0.1.2" }

POST /evaluate

Request body:

{
  "rules": [
    {
      "id": "rule-1",
      "version": 1,
      "model": "FLAT_RATE",
      "params": { "rate": 0.18, "base": "grossSalary" },
      "priority": 1,
      "effectiveFrom": "2024-01-01T00:00:00.000Z",
      "effectiveUntil": null,
      "tags": ["togo", "irpp"],
      "checksum": "abc123"
    }
  ],
  "input": {
    "requestId": "req-001",
    "data": { "grossSalary": 2500000 },
    "meta": { "tenantId": "tenant-1" }
  }
}

Response 200: EvaluationResult (JSON serialized)

Error responses:

Status	Condition
400	Malformed input or ValidationError
409	RuleConflictError
422	Other PPEError
503	SnapshotFailureError
500	Unexpected error

Programmatic usage

import { createApp } from '@run-iq/server';

const app = createApp({
  plugins: [myPlugin],
  dsls: [myDsl],
  strict: false,
  logLevel: 'silent',
});

// Use app.inject() for testing
const response = await app.inject({
  method: 'POST',
  url: '/evaluate',
  payload: { rules: [...], input: {...} },
});

Configuration

Option	Type	Default	Description
port	number	3000	Listen port
host	string	'0.0.0.0'	Listen host
plugins	PPEPlugin[]	required	PPE plugins to register
dsls	DSLEvaluator[]	required	DSL evaluators to register
snapshot	ISnapshotAdapter	—	Snapshot adapter
strict	boolean	true	Strict mode
timeout	object	—	Timeout config (dsl, hook, pipeline)
logLevel	string	'info'	'info' | 'warn' | 'error' | 'silent'

License

MIT — Abdou-Raouf ATARMLA