Parties

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 "Parties" API
Attach first/second party (and witness) details to an e-Stamp order.

ENDPOINT: POST /v1/estamp/orders/:orderId/parties
- Attach/correct e-Stamp order party (customer) details
- Required scope: estamp.parties.write
- Parameters:
  - orderId (path, required): The e-Stamp order id.
  - customerName (string, optional): Customer's full name.
  - partyName (string, optional): Counter-party's full name.
  - customerMobile (string, optional): Customer's mobile number.
  - customerEmail (string, optional): Customer's email address.
  - partyAddress (string, optional): Party's address.
  - partyPan (string, optional): Party's PAN.
- Example request body: {"customerName":"Rahul Kumar","customerMobile":"+919876543210","customerEmail":"[email protected]"}

Rules for this e-Stamp step
- This is one step of the e-Stamp order flow: services -> state/instrument/article -> schema -> duty -> order -> parties -> payment -> status -> documents.
- Build the form from the schema endpoint and do not invent e-Stamp fields.
- Send an Idempotency-Key header on order creation, store the order id, and make the flow resumable.
- Poll order status with backoff until a final status. Download documents through my backend, never from the browser with the key.
- If an endpoint returns 404 or is not enabled for my key, stop and ask me rather than guessing.

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.