x402-pqs 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# x402-pqs
+
+Express middleware that scores prompts via [PQS (Prompt Quality Score)](https://pqs.onchainintel.net) before they hit any LLM endpoint.
+
+Built for x402-enabled agent workflows. Free tier — no wallet required.
+
+## Install
+```bash
+npm install x402-pqs
+```
+
+## Usage
+```javascript
+const express = require("express");
+const { pqsMiddleware } = require("x402-pqs");
+
+const app = express();
+app.use(express.json());
+
+// Score all prompts, warn if below 10/40
+app.use(pqsMiddleware({
+  threshold: 10,
+  vertical: "crypto",
+  onLowScore: "warn",
+}));
+
+app.post("/api/chat", (req, res) => {
+  // req.pqs contains the score result
+  console.log("Prompt score:", req.pqs.score, req.pqs.grade);
+  res.json({ message: "ok" });
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| threshold | number | 0 | Block/warn prompts scoring below this |
+| vertical | string | "general" | Scoring vertical: crypto, content, research, general |
+| onLowScore | string | "warn" | warn, block, or ignore low scores |
+| promptField | string | "prompt" | Request body field containing the prompt |
+| onScore | function | null | Callback with score result |
+
+## Response Headers
+
+Every request gets these headers added:
+- `X-PQS-Score` — numeric score (0-40)
+- `X-PQS-Grade` — letter grade (A-F)
+- `X-PQS-Out-Of` — maximum score (40)
+
+## Powered by
+
+[PQS — Prompt Quality Score](https://pqs.onchainintel.net) | Built by [OnChainIntel](https://onchainintel.net)
+
+The world's first named AI prompt quality score. 8 attributes. 5 frameworks. 1 score.

package/index.d.ts

@@ -0,0 +1,21 @@
+export interface PQSResult {
+  pqs_version: string;
+  prompt: string;
+  vertical: string;
+  score: number;
+  out_of: number;
+  grade: "A" | "B" | "C" | "D" | "F";
+  upgrade: string;
+  powered_by: string;
+}
+
+export interface PQSMiddlewareOptions {
+  threshold?: number;
+  vertical?: "crypto" | "content" | "research" | "general";
+  onLowScore?: "warn" | "block" | "ignore";
+  promptField?: string;
+  onScore?: (result: PQSResult, req: any, res: any) => void;
+}
+
+export function pqsMiddleware(options?: PQSMiddlewareOptions): (req: any, res: any, next: any) => Promise<void>;
+export function scorePrompt(prompt: string, vertical?: string): Promise<PQSResult | null>;

package/index.js

@@ -0,0 +1,61 @@
+const PQS_FREE_ENDPOINT = "https://pqs.onchainintel.net/api/score/free";
+
+async function scorePrompt(prompt, vertical = "general") {
+  const res = await fetch(PQS_FREE_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ prompt, vertical }),
+  });
+  if (!res.ok) return null;
+  return await res.json();
+}
+
+function pqsMiddleware(options = {}) {
+  const {
+    threshold = 0,
+    vertical = "general",
+    onLowScore = "warn",
+    promptField = "prompt",
+    onScore = null,
+  } = options;
+
+  return async function (req, res, next) {
+    const prompt = req.body && req.body[promptField];
+    if (!prompt) return next();
+
+    try {
+      const result = await scorePrompt(prompt, vertical);
+      if (!result) return next();
+
+      req.pqs = result;
+      res.setHeader("X-PQS-Score", result.score);
+      res.setHeader("X-PQS-Grade", result.grade);
+      res.setHeader("X-PQS-Out-Of", result.out_of);
+
+      if (onScore && typeof onScore === "function") {
+        onScore(result, req, res);
+      }
+
+      if (result.score < threshold) {
+        if (onLowScore === "block") {
+          return res.status(400).json({
+            error: "Prompt quality too low",
+            pqs_score: result.score,
+            pqs_grade: result.grade,
+            pqs_out_of: result.out_of,
+            upgrade: result.upgrade,
+          });
+        } else if (onLowScore === "warn") {
+          console.warn(`[x402-pqs] Low prompt score: ${result.score}/${result.out_of} (${result.grade})`);
+        }
+      }
+
+      return next();
+    } catch (err) {
+      console.error("[x402-pqs] Scoring error:", err.message);
+      return next();
+    }
+  };
+}
+
+module.exports = { pqsMiddleware, scorePrompt };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "x402-pqs",
+  "version": "1.0.0",
+  "description": "Express middleware that scores prompts via PQS (Prompt Quality Score) before they hit any LLM endpoint",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "x402",
+    "pqs",
+    "prompt-quality",
+    "llm",
+    "ai",
+    "middleware",
+    "express"
+  ],
+  "author": "OnChainIntel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OnChainAIIntel/x402-pqs"
+  },
+  "homepage": "https://pqs.onchainintel.net",
+  "dependencies": {
+    "x402-pqs": "github:OnChainAIIntel/x402-pqs"
+  }
+}