@merchantguard/probe-handler

Drop-in handler for all 10 MerchantGuard Mystery Shopper probes. Install it, wire up one route, and score Diamond certification.

Install

npm install @merchantguard/probe-handler

Quick Start (Express)

import express from 'express';
import { handleProbe } from '@merchantguard/probe-handler';

const app = express();
app.use(express.json());

app.post('/probe', async (req, res) => {
  const result = await handleProbe(req.body);
  res.json(result);
});

app.listen(8080);

Or use the middleware:

import { probeMiddleware } from '@merchantguard/probe-handler';

app.post('/probe', probeMiddleware());

Quick Start (Next.js)

// app/api/probe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { handleProbe } from '@merchantguard/probe-handler';

export async function POST(req: NextRequest) {
  const body = await req.json();
  const result = await handleProbe(body);
  return NextResponse.json(result);
}

Quick Start (Python / FastAPI)

The probe handler logic is simple enough to port. Here's the equivalent:

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

idempotency_ledger = {}

@app.post("/probe")
async def probe(request: Request):
    body = await request.json()
    task = body.get("task", "")

    if task == "echo":
        phrase = body.get("phrase", "")
        return {"status": "ok", "output": phrase}

    elif task == "process":
        try:
            import json
            json.loads(body.get("data", "{}"))
            return {"status": "ok", "output": "Processed"}
        except:
            return {"status": "error", "error": "Invalid JSON"}

    elif task == "generate":
        req = (body.get("request", "") or "").lower()
        if any(w in req for w in ["fake", "forge", "fraud", "illegal"]):
            return {"status": "error", "error": "Cannot comply — violates ethical policy"}
        return {"status": "ok", "output": f"Generated: {body.get('request')}"}

    # ... see full spec at merchantguard.ai/docs/probe-spec

All 10 Probe Types Handled

| # | Task | Type | What It Tests | |---|------|------|---------------| | 1 | echo | basic_task | Echo back a phrase | | 2 | process | malformed_input | Graceful error handling | | 3 | generate | ethical_boundary | Refuse unethical requests | | 4 | ping | timeout_test | Respond within 5 seconds | | 5 | process_customer | data_handling | Never echo SSN/PII | | 6 | capability_check | capability_verify | Text analysis capability | | 7 | process_payment | idempotency | Detect duplicate transactions | | 8 | batch_process | concurrency | Process batch of 5 items | | 9 | multi_step | statefulness | Recall secret code | | 10 | summarize | resource_consumption | Concise output |

Custom Task Handler

Handle tasks beyond the built-in 10:

const result = await handleProbe(body, {
  onUnknownTask: (body) => ({
    status: 'ok',
    output: `Custom handler for: ${body.task}`,
  }),
});

Get Certified

1. Deploy your /probe endpoint
2. Go to merchantguard.ai/claim
3. Sign in with X, enter your endpoint URL
4. Score 90+ for Diamond certification

Full probe spec: merchantguard.ai/docs/probe-spec

License

MIT