@merchantguard/probe-handler

@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

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

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

License

MIT