Backend Response Contracts

This frontend consumes multiple backend response contracts. Do not force every route into one JSON envelope.

Sources

• clab-assistant-v1 Django API returns successful application payloads as {"status": "ok", ...} for endpoints such as /preview, /measures, /measurements/chart, /patterns/available, /pattern/editable, /pattern/groups, /materials, /piece-codes, and /genders.

• clab-assistant-v1 Django middleware can return auth errors as {"error": "..."}.

• clab-estimator-v1 is the Nesting/Estimator service consumed through NESTING_API_URL; frontend proxy routes should preserve its job/result payloads.

• Internal Next.js API routes can use the local successResponse / errorResponse envelope when they are not acting as compatibility adapters or transparent proxies.

Clab Estimator (clab-estimator-v1)

src/app/api/fabric-layout/v2/** proxies the estimator service. Keep these routes thin: authenticate the caller, issue the workspace-scoped estimator token, normalize local request fields only when needed, and preserve estimator success payloads.

Observed estimator shapes:

• POST /api/v1/nesting/jobs returns {"job_id": "...", "status": "queued"} with HTTP 201.

• GET /api/v1/nesting/jobs/:jobId returns job status fields such as id, status, progress, timestamps, duration_seconds, is_terminal, meta, metrics, error_message, and result_url.

• POST /api/v1/nesting/jobs/:jobId/retry, POST /cancel, and POST /jobs/cancel-all return job/cancel status payloads and can use non-200 statuses such as 202 or 409.

• GET /api/v1/nesting/results returns the estimator/S3 results list payload, including pagination fields controlled by cursor and limit.

• GET /api/v1/nesting/results/:jobId returns raw result.json.

• GET /api/v1/nesting/results/:jobId/summary returns the summary object with job_id, run_id, materials, materials_count, has_multiple_materials, meta, fabric, and metrics.

• GET /api/v1/nesting/results/:jobId/export.hpgl returns an HPGL attachment, not JSON.

• Estimator errors can be {"error": "..."}, {"detail": "..."}, {"description": "..."}, or {"message": "..."} with additional details that must be preserved for debugging.

Frontend guardrails:

• src/lib/services/clabEstimatorApi.ts owns NESTING_API_URL validation and estimator error parsing.

• src/lib/services/clabEstimatorApi.test.ts covers helper behavior.

• src/app/api/fabric-layout/v2/estimator-contract.test.ts covers the proxy contract for job detail, history list, summary, HPGL attachments, and retry conflict errors.

Change Procedure

When a Django or Estimator response changes:

1. Update or add a contract case in src/lib/services/clabApiClient.contract.test.ts, src/app/api/fabric-layout/v2/estimator-contract.test.ts, or the relevant route test.

2. Update the frontend adapter/proxy boundary only. Do not change unrelated internal API envelopes.

3. Run npm run check, the affected route/client tests, and npm run build.

4. Keep backward-compatible parsing when existing saved projects or deployed backend versions can still send the old shape.