Asynchronous work

import time, requests

def wait_for_job(job_id: str, token: str, region: str,
                 timeout: float = 600, interval: float = 3) -> dict:
    """Block until a job reaches a terminal state. Raises on failure or timeout."""
    headers = {"Authorization": f"Bearer {token}", "X-Region-Context": region}
    deadline = time.monotonic() + timeout
    while True:
        r = requests.get(
            f"https://api.stg.simnet.cloud/api/v1/jobs/{job_id}",
            headers=headers, timeout=30,
        )
        r.raise_for_status()
        job = r.json()
        status = job.get("status")
        if status == "success":
            return job
        if status == "error":
            # The reason is on the job. Retrying the original request will not fix
            # a quota ceiling or a zone with no capacity.
            raise RuntimeError(f"job {job_id} failed: {job.get('detail') or job}")
        if time.monotonic() > deadline:
            # Deliberately not a failure: the job may still complete. Surface it as
            # "unknown" so the caller checks rather than retries.
            raise TimeoutError(f"job {job_id} still {status} after {timeout}s")
        time.sleep(interval)

type Job = { jobId: string; status: "running" | "success" | "error"; detail?: string };

/** Blocks until a job is terminal. Throws on failure or timeout. */
export async function waitForJob(
  jobId: string,
  token: string,
  region: string,
  { timeoutMs = 600_000, intervalMs = 3_000 } = {},
): Promise<Job> {
  const deadline = Date.now() + timeoutMs;
  for (;;) {
    const res = await fetch(`https://api.stg.simnet.cloud/api/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${token}`, "X-Region-Context": region },
    });
    if (!res.ok) throw new Error(`job read failed: ${res.status}`);
    const job = (await res.json()) as Job;

    if (job.status === "success") return job;
    if (job.status === "error") throw new Error(`job ${jobId} failed: ${job.detail ?? "no reason given"}`);
    // Timing out is not the same as failing — the job may yet succeed, so the
    // caller must check rather than resend the original request.
    if (Date.now() > deadline) throw new Error(`job ${jobId} still running after ${timeoutMs}ms`);
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}