[PlanSight Partner API v1.0.0 · build 7acb0c07c2f1a3ee0ae1476b4d7bf3f05dc96bba · https://plansight.xyz]

You are adding a "PlanSight" integration to our construction job-management app
(we bid, estimate, and pay for work). PlanSight is an AI building-plan code-review
service. Your job: let our users upload plans, see PlanSight's scan results, and
ask questions about a plan — all inside our app.

AUTHORITATIVE DOCS (read these first, in full):
- Guide:   https://plansight.xyz/developers
- OpenAPI: https://plansight.xyz/api/v1/openapi.json   (every endpoint + exact request/response schemas)

CREDENTIALS
- We have a PlanSight API key in the server env var PLANSIGHT_API_KEY (format ps_live_...).
- It is a SERVER-SIDE SECRET. NEVER send it to the browser, log it, or commit it.
- Every server-to-server call: header  Authorization: Bearer $PLANSIGHT_API_KEY
- Our PlanSight account owns everything we send; one "job" in PlanSight === one of our jobs.

BUILD THE FOLLOWING

1) A small server-side PlanSight client (e.g. lib/plansight.ts) that wraps:
   POST https://plansight.xyz/api/v1/jobs                         -> { jobId, versionId }   (create)
   POST https://plansight.xyz/api/v1/jobs/{jobId}/files           -> { fileId, uploadUrl }  (then PUT the PDF bytes to uploadUrl with Content-Type: application/pdf)
   POST https://plansight.xyz/api/v1/jobs/{jobId}/scan            -> starts the scan (async)
   GET  https://plansight.xyz/api/v1/jobs/{jobId}                 -> { status, pipeline }    (poll until complete/failed)
   GET  https://plansight.xyz/api/v1/jobs/{jobId}/findings        -> { findings: [...] }
   POST https://plansight.xyz/api/v1/jobs/{jobId}/chat            -> { answer, citations }
   POST https://plansight.xyz/api/v1/embed { screen, jobId? }     -> { url, expiresAt }      (signed hosted-screen link)

2) On each of our jobs, store the PlanSight jobId. Add an "Upload plans for review"
   action: create a PlanSight job, get a presigned URL, PUT the PDF, then call scan.
   Track status by polling GET /api/v1/jobs/{jobId} (or show our own progress).

3) Add a "PlanSight" screen/tab to each job offering THREE things (use the hosted
   screens — do NOT rebuild PlanSight's UI). For each, call POST /api/v1/embed from
   OUR SERVER (with the API key), then render the returned url in an <iframe>:
   - results:  POST /api/v1/embed { screen: "job",  jobId }  -> iframe the url (marked-up plan + findings, with upload)
   - jobChat:  POST /api/v1/embed { screen: "chat", jobId }  -> iframe the url (ask questions, AI answers)
   - a "Log in to PlanSight" button: POST /api/v1/embed { screen: "login" } -> open the url (their full PlanSight dashboard)
   Embed links expire in ~30 minutes and are scoped to one screen + one job — mint them
   fresh, server-side, when the user opens the screen. NEVER mint them in the browser.

4) (Optional, great for a bid/estimate app) Also pull GET /api/v1/jobs/{jobId}/findings
   server-side and show a NATIVE summary on the job card — counts by severity and any
   cost impact — with an "Open full report" button that opens the embedded results screen.

RULES
- Match the exact shapes in the OpenAPI spec. Handle 401 (bad key), 404 (job not found
  / not ours), and 429 (rate limited — respect the Retry-After header).
- Keep the API key server-side always; the browser only ever sees short-lived embed URLs.
- Scans are asynchronous (minutes); design the UI around "submitted -> processing -> ready".

Confirm your integration plan, then implement it incrementally with tests.