Hyperspell Documentation Audit

The bones are good — there's an llms.txt, a Stainless-hosted OpenAPI spec, an MCP server, and a Claude Code skill for agent-driven install. But the actual prose and snippets are riddled with copy-paste contamination, broken code examples, and three different casings for the same parameter. An agent pasting these snippets verbatim will not get a working app.

2. Webhook verifier example is broken in every meaningful way (critical)

Location: /usage/webhooks

Problem: This is the canonical security primitive for webhook integrators, and both language examples are full of compile-time errors before you can even reach the cryptography.

Python version (at least four undefined references):

from fastapi import FastAPI, Request
import hashlib
import hmac

def verify_webhook(payload, secret):
    hash = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(signagture, hash)   # `signagture` is a typo AND never passed in

class WebhookPayload(pydantic.BaseModel):   # `pydantic` is never imported
    ...

app = FastAPI()

@router.post("/webhooks/hyperspell")   # `router` is never defined — only `app` is
async def hyperspell_webhook(query: WebhookPayload, request: Request):
    signature = request.headers.get("X-Hyperspell-Signature")
    if not verify_webhook(query, HYPERSPELL_JWT_SECRET):   # global never set or imported
        ...

Four separate NameErrors: signagture (typo), pydantic (no import), router (only app exists), HYPERSPELL_JWT_SECRET (never sourced from env). Also verify_webhook(query, ...) passes only two arguments, so even if the typo is fixed there is no signature variable available to compare.

TypeScript version is worse still:

function verify_webhook(payload: WebhookPayload, secret: string) {
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
  return hmac.compare_digest(sig, expected);
}

export async function POST(req: Request) {
  ...
  if (!verify_webhook(payload, secret)) return NextResponse.json(...);   // payload used before declaration
  const payload = JSON.parse(raw.toString("utf8")) as WebhookPayload;    // declared after use
}

Three layered bugs: (a) payload is referenced before it's declared; (b) the function signature takes WebhookPayload — a parsed object — and crypto.createHmac().update(payload) will coerce it to the string "[object Object]", so even after fixing the order of declarations the HMAC is computed over garbage and will never match; (c) the call doesn't belong in Node at all.