Vehicle RC

I'm using Claude to build this.

Integrate the StampMitra API (Indian identity verification and e-Stamp Paper) into my app.

API facts (source of truth: https://developer.stampmitra.in/llms.txt)
- Base URL: https://api-b2b.stampmitra.in
- Auth: send "Authorization: Bearer <key>" (or "x-api-key: <key>") on every request
- Requests and responses are JSON. Send Content-Type: application/json on POST.
- Use a SANDBOX key (sk_test_...) while building. Read it from the environment variable STAMPMITRA_API_KEY.
- Never hard-code the key, never expose it to the browser, never log it.
- Call StampMitra only from server-side code. The UI calls my own backend route.

How to build it
- First inspect my project: language, framework, package manager, HTTP client, test runner and folder conventions. Follow them. If the project is empty, ask which stack I want before writing code.
- The official StampMitra SDKs (Node.js, Python, PHP, Java, Go, .NET, Ruby) are pre-release 0.1.0 and not yet published to npm, PyPI, Packagist, Maven Central, the Go module proxy, NuGet or RubyGems, so do not run an install command for them. Call the REST API over HTTPS with the HTTP client my project already uses. Do not install or invent a StampMitra package.
- Put every StampMitra call in ONE small client module. It adds the auth header, applies a 15 second timeout and turns error responses into a typed error with status, code, message and requestId.
- Add STAMPMITRA_API_KEY to .env.example with a placeholder (sk_test_xxx). Fail fast at startup with a clear message if it is missing. Never commit real keys.

Error handling (every error body is { error: { code, message, requestId } })
- 400 BAD_REQUEST: invalid input. Show a field-level message. Do not retry.
- 401 UNAUTHORIZED: key missing or invalid. This is my configuration problem, not the end user's. Show a generic "service unavailable" message, log the requestId, do not retry.
- 402 PAYMENT_REQUIRED: not enough wallet balance (production). Surface it to me as an operational alert, not to the end user.
- 403 FORBIDDEN: the key lacks the required scope or the service is not enabled. Say which scope the endpoint needs.
- 404 NOT_FOUND: wrong id or path. Do not retry.
- 429 TOO_MANY_REQUESTS: rate limit or quota. Retry at most 3 times with exponential backoff and jitter (honour Retry-After if present), then show a friendly "try again shortly" message.
- 5xx / 502 / network timeout: retry reads (GET) up to 2 times. For POST calls retry at most once, then show a friendly message.
- Log requestId and referenceId with every failure. Never log the API key, a full PAN, bank account number or whole response bodies.

TASK: Integrate the StampMitra "Vehicle RC" API
Verify a Vehicle RC in real time.
Production service code: rc.verify

ENDPOINT: POST /v1/verify/rc
- Verify Vehicle RC
- Required scope: verification.rc.read
- Parameters:
  - vehicleNumber (string, required): Vehicle registration number.
- Example request body: {"vehicleNumber":"MH12AB1234"}
- Response fields: referenceId, regNo, registrationStatus, ownerName, ownerFatherName, vehicleClass, vehicleManufacturerName, model, vehicleColor, chassis, engine, registrationDate, rcStatus, rcExpiryDate, insuranceUpto, isCommercial
- Example response: {"referenceId":"SMV-20260927-3D71Q9","regNo":"MH12AB1234","registrationStatus":"VALID","ownerName":"RAHUL KUMAR","ownerFatherName":"SURESH KUMAR","vehicleClass":"LMV","vehicleManufacturerName":"MARUTI SUZUKI","model":"SWIFT","vehicleColor":"WHITE","chassis":"MA3ERLF1S00123456","engine":"K12MN1234567","registrationDate":"2019-05-14","rcStatus":"ACTIVE","rcExpiryDate":"2034-05-13","insuranceUpto":"2025-05-13","isCommercial":false}
- Errors this endpoint can return:
  - 401 UNAUTHORIZED: Missing or invalid API key
  - 403 FORBIDDEN: Valid key, missing required scope
  - 400 BAD_REQUEST: Validation error
  - 402 PAYMENT_REQUIRED: Insufficient wallet balance
  - 429 TOO_MANY_REQUESTS: Rate limited
  - 502 INTERNAL_ERROR: Upstream verification service unreachable
- Notes: Input format is validated up front - a malformed pan/gstin/etc. fails fast with a 400 rather than being submitted for verification. referenceId (format SMV-YYYYMMDD-XXXXXXX) is StampMitra's own transaction id for this call and is always present, including on a negative (valid: false / found: false) result - both positive and negative determinations are completed, billable verifications. This is not an idempotency key.

Rules for this verification
- Validate vehicleNumber on client and server before calling. A malformed value returns 400.
- "valid": false (or found: false) is a completed, billable verification. Show a clear "not valid" result, not a crash.
- Mask sensitive identifiers in the UI after submit and never log them in full.
- Store referenceId, the outcome and a timestamp with the record for audit. Do not re-call on every page load: cache per record.
- Build: one backend route that calls StampMitra, one small form, and a result card with loading, success, not-valid and error states.

Test in Sandbox
- A successful call, a validation failure (expect 400), a missing or wrong key (expect 401) and the 429 / 5xx retry path.

How I want you to work:
1. Before writing code, list the files you will create or change and the plan in 5-8 bullets. Then implement without pausing for approval.
2. If the StampMitra MCP server (@stampmitra/mcp-server) is connected, use it to run real sandbox calls and check the response shape before coding against it.
3. Write tests for the API client module and the validation (mock the HTTP layer).
4. At the end, summarise what you changed, how to run it and what I must do manually (add the key, restart the server).

Acceptance checklist:
- Works end to end in Sandbox with the real response fields (no mocked data in the final path)
- No secrets in client code, logs, URLs or git
- Clear loading, empty and error states, including 400, 401, 402, 403, 429 and 5xx
- referenceId (and requestId on failures) is stored or logged for audit
- Inputs are validated on client and server, and sensitive values are masked in the UI
- Tests cover the API client, validation and at least one error path
- A short note on how to run it and how to switch from Sandbox to production later
- If anything is missing (like my key), ask me. Do not guess endpoints, fields or values.