pot-api 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# pot-api
+
+REST API server for [pot-sdk](https://npmjs.com/package/pot-sdk) — sync and async AI output verification with webhook callbacks.
+
+## What it does
+
+pot-api wraps pot-sdk as an HTTP server. Fire a verification request and get the result synchronously, or use async mode to get a `jobId` immediately while verification runs in the background — with optional webhook push on completion.
+
+## Install & Run
+
+```bash
+# Run directly
+ANTHROPIC_API_KEY=... XAI_API_KEY=... npx pot-api
+
+# Or install globally
+npm install -g pot-api
+pot-api
+```
+
+Default port: `3141`. Override with `PORT=8080`.
+
+## Endpoints
+
+### `POST /verify` — Sync
+Blocks until verification is complete (~5–30s depending on tier).
+
+```bash
+curl -X POST http://localhost:3141/verify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "output": "The Eiffel Tower is 330m tall.",
+    "question": "How tall is the Eiffel Tower?",
+    "tier": "basic"
+  }'
+```
+
+Returns: `VerificationResult` (confidence, flags, mdi, sas, dissent, synthesis)
+
+### `POST /verify/async` — Async + Webhook
+Returns `{jobId}` immediately. Verification runs in background.
+
+```bash
+curl -X POST http://localhost:3141/verify/async \
+  -H "Content-Type: application/json" \
+  -d '{
+    "output": "The Eiffel Tower is 330m tall.",
+    "question": "How tall is the Eiffel Tower?",
+    "tier": "basic",
+    "callbackUrl": "https://your-agent.example.com/webhook"
+  }'
+
+# → {"jobId":"abc-123","status":"pending","pollUrl":"/jobs/abc-123"}
+```
+
+When done, pot-api POSTs to your `callbackUrl`:
+```json
+{
+  "jobId": "abc-123",
+  "status": "done",
+  "result": { "verified": true, "confidence": 0.91, ... }
+}
+```
+
+### `GET /jobs/:id` — Poll Status
+```bash
+curl http://localhost:3141/jobs/abc-123
+# → {"id":"abc-123","status":"running","input":{...}}
+# → {"id":"abc-123","status":"done","result":{...}}
+```
+
+Status values: `pending` → `running` → `done` | `error`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | ✅ Required |
+| `XAI_API_KEY` | Optional extra generator |
+| `DEEPSEEK_API_KEY` | Optional extra generator |
+| `MOONSHOT_API_KEY` | Optional extra generator |
+| `PORT` | Server port (default: 3141) |
+
+## Per-request API keys (BYOK)
+
+Override keys per request:
+```json
+{
+  "output": "...",
+  "question": "...",
+  "apiKeys": {
+    "anthropic": "sk-ant-...",
+    "xai": "xai-..."
+  }
+}
+```
+
+## Links
+
+- pot-sdk: https://npmjs.com/package/pot-sdk
+- pot-mcp: https://npmjs.com/package/pot-mcp
+- Protocol spec: https://thoughtproof.ai
+- GitHub: https://github.com/ThoughtProof/pot-api

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface ApiKeys {
+    anthropic?: string;
+    xai?: string;
+    deepseek?: string;
+    moonshot?: string;
+}
+export declare function resolveKeys(override?: ApiKeys): ApiKeys;
+export declare function buildApiKeyRecord(keys: ApiKeys): Record<string, string>;
+export declare function validateConfig(keys: ApiKeys): string | null;

package/dist/config.js

@@ -0,0 +1,26 @@
+export function resolveKeys(override) {
+    return {
+        anthropic: override?.anthropic ?? process.env.ANTHROPIC_API_KEY,
+        xai: override?.xai ?? process.env.XAI_API_KEY,
+        deepseek: override?.deepseek ?? process.env.DEEPSEEK_API_KEY,
+        moonshot: override?.moonshot ?? process.env.MOONSHOT_API_KEY,
+    };
+}
+export function buildApiKeyRecord(keys) {
+    const record = {};
+    if (keys.anthropic)
+        record['anthropic'] = keys.anthropic;
+    if (keys.xai)
+        record['xai'] = keys.xai;
+    if (keys.deepseek)
+        record['deepseek'] = keys.deepseek;
+    if (keys.moonshot)
+        record['moonshot'] = keys.moonshot;
+    return record;
+}
+export function validateConfig(keys) {
+    if (!keys.anthropic) {
+        return 'ANTHROPIC_API_KEY is required.';
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import express from 'express';
+import { verify } from 'pot-sdk';
+import { resolveKeys, buildApiKeyRecord, validateConfig } from './config.js';
+import { createJob, getJob, updateJob } from './jobs.js';
+const app = express();
+app.use(express.json({ limit: '1mb' }));
+const PORT = parseInt(process.env.PORT ?? '3141', 10);
+// ─── Health ───────────────────────────────────────────────
+app.get('/', (_req, res) => {
+    res.json({ name: 'pot-api', version: '0.1.0', status: 'ok' });
+});
+// ─── Sync verify ──────────────────────────────────────────
+app.post('/verify', async (req, res) => {
+    const { output, question, tier = 'basic', apiKeys } = req.body;
+    if (!output || !question) {
+        res.status(400).json({ error: 'output and question are required' });
+        return;
+    }
+    const keys = resolveKeys(apiKeys);
+    const configError = validateConfig(keys);
+    if (configError) {
+        res.status(400).json({ error: configError });
+        return;
+    }
+    try {
+        const result = await verify(output, {
+            tier,
+            apiKeys: buildApiKeyRecord(keys),
+            question,
+        });
+        res.json(result);
+    }
+    catch (err) {
+        res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+    }
+});
+// ─── Async verify ─────────────────────────────────────────
+app.post('/verify/async', (req, res) => {
+    const { output, question, tier = 'basic', callbackUrl, apiKeys } = req.body;
+    if (!output || !question) {
+        res.status(400).json({ error: 'output and question are required' });
+        return;
+    }
+    const keys = resolveKeys(apiKeys);
+    const configError = validateConfig(keys);
+    if (configError) {
+        res.status(400).json({ error: configError });
+        return;
+    }
+    const job = createJob({ output, question, tier, callbackUrl });
+    res.status(202).json({ jobId: job.id, status: 'pending', pollUrl: `/jobs/${job.id}` });
+    // Run in background
+    runJob(job.id, output, question, tier, buildApiKeyRecord(keys), callbackUrl);
+});
+// ─── Poll job status ───────────────────────────────────────
+app.get('/jobs/:id', (req, res) => {
+    const job = getJob(req.params.id);
+    if (!job) {
+        res.status(404).json({ error: 'Job not found' });
+        return;
+    }
+    res.json(job);
+});
+// ─── Background runner + webhook push ────────────────────
+async function runJob(jobId, output, question, tier, apiKeys, callbackUrl) {
+    updateJob(jobId, { status: 'running' });
+    try {
+        const result = await verify(output, { tier, apiKeys, question });
+        updateJob(jobId, { status: 'done', result });
+        if (callbackUrl) {
+            await pushWebhook(callbackUrl, { jobId, status: 'done', result });
+        }
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        updateJob(jobId, { status: 'error', error });
+        if (callbackUrl) {
+            await pushWebhook(callbackUrl, { jobId, status: 'error', error });
+        }
+    }
+}
+async function pushWebhook(url, payload) {
+    try {
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
+        console.warn(`[pot-api] Webhook delivery failed for ${url}:`, err);
+    }
+}
+// ─── Start ────────────────────────────────────────────────
+app.listen(PORT, () => {
+    console.log(`🔍 pot-api running on http://localhost:${PORT}`);
+    console.log(`   POST /verify          — sync verification`);
+    console.log(`   POST /verify/async    — async + webhook`);
+    console.log(`   GET  /jobs/:id        — poll status`);
+});

package/dist/jobs.d.ts

@@ -0,0 +1,18 @@
+export type JobStatus = 'pending' | 'running' | 'done' | 'error';
+export interface Job {
+    id: string;
+    status: JobStatus;
+    createdAt: string;
+    updatedAt: string;
+    input: {
+        output: string;
+        question: string;
+        tier: 'basic' | 'pro';
+        callbackUrl?: string;
+    };
+    result?: unknown;
+    error?: string;
+}
+export declare function createJob(input: Job['input']): Job;
+export declare function getJob(id: string): Job | undefined;
+export declare function updateJob(id: string, patch: Partial<Job>): void;

package/dist/jobs.js

@@ -0,0 +1,31 @@
+import { randomUUID } from 'crypto';
+const store = new Map();
+// Auto-cleanup jobs older than 1h
+setInterval(() => {
+    const cutoff = Date.now() - 60 * 60 * 1000;
+    for (const [id, job] of store.entries()) {
+        if (new Date(job.createdAt).getTime() < cutoff) {
+            store.delete(id);
+        }
+    }
+}, 10 * 60 * 1000);
+export function createJob(input) {
+    const job = {
+        id: randomUUID(),
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        input,
+    };
+    store.set(job.id, job);
+    return job;
+}
+export function getJob(id) {
+    return store.get(id);
+}
+export function updateJob(id, patch) {
+    const job = store.get(id);
+    if (job) {
+        Object.assign(job, patch, { updatedAt: new Date().toISOString() });
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pot-api",
+  "version": "0.1.0",
+  "description": "REST API server for pot-sdk — sync and async AI output verification with webhook callbacks",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pot-api": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "express": "^4.18.0",
+    "pot-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^25.3.0",
+    "typescript": "^5.3.0"
+  }
+}