From 7fc3e0bb7e41d89742dbd630d4041b9dc7aa657a Mon Sep 17 00:00:00 2001
From: Robin Nicollet <robin.nicollet@nabla.com>
Date: Wed, 15 Jul 2026 13:35:11 +0200
Subject: [PATCH 1/2] Replace sync normalized-data with async submit + poll
 flow (API-432).

Showcase the recommended integration pattern for generate-normalized-data-async with a shared pollUntilSucceeded helper.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 frontend/src/api/async-job.ts                 | 33 +++++++++++++++++++
 frontend/src/api/normalize.ts                 | 22 +++++++++----
 .../work-on-note.render.ts                    |  2 +-
 frontend/src/shared/documentationLinks.ts     |  3 +-
 4 files changed, 51 insertions(+), 9 deletions(-)
 create mode 100644 frontend/src/api/async-job.ts

diff --git a/frontend/src/api/async-job.ts b/frontend/src/api/async-job.ts
new file mode 100644
index 0000000..ecd2e42
--- /dev/null
+++ b/frontend/src/api/async-job.ts
@@ -0,0 +1,33 @@
+export type AsyncJobStatus = "ONGOING" | "SUCCEEDED" | "FAILED";
+
+export interface AsyncJob<TPayload = unknown> {
+  id: string;
+  status: AsyncJobStatus;
+  payload?: TPayload;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+
+export async function pollUntilSucceeded<TPayload>(
+  fetchJob: () => Promise<AsyncJob<TPayload>>,
+  options: { intervalMs?: number } = {},
+): Promise<TPayload> {
+  const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+  while (true) {
+    const job = await fetchJob();
+
+    if (job.status === "SUCCEEDED") {
+      if (job.payload === undefined) {
+        throw new Error("Async job succeeded but returned no payload.");
+      }
+      return job.payload;
+    }
+
+    if (job.status === "FAILED") {
+      throw new Error(`Async job ${job.id} failed.`);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
diff --git a/frontend/src/api/normalize.ts b/frontend/src/api/normalize.ts
index a3862b8..7c3e99a 100644
--- a/frontend/src/api/normalize.ts
+++ b/frontend/src/api/normalize.ts
@@ -1,3 +1,4 @@
+import { type AsyncJob, pollUntilSucceeded } from "./async-job.js";
 import { nablaFetch } from "../transport/client.js";
 import type { ClinicalNote } from "./note.js";
 
@@ -18,11 +19,18 @@ export interface NormalizedData {
 export async function generateNormalizedData(
   note: ClinicalNote,
 ): Promise<NormalizedData> {
-  const response = await nablaFetch("/v1/core/user/generate-normalized-data", {
-    method: "POST",
-    body: JSON.stringify({
-      note,
-    }),
-  });
-  return response.json() as Promise<NormalizedData>;
+  const submitResponse = await nablaFetch(
+    "/v1/core/user/generate-normalized-data-async",
+    {
+      method: "POST",
+      body: JSON.stringify({ note }),
+    },
+  );
+  const { id } = (await submitResponse.json()) as AsyncJob;
+
+  return pollUntilSucceeded<NormalizedData>(() =>
+    nablaFetch(`/v1/core/user/generate-normalized-data-async/${id}`).then(
+      (response) => response.json() as Promise<AsyncJob<NormalizedData>>,
+    ),
+  );
 }
diff --git a/frontend/src/pages/full-encounter-demo/work-on-note.render.ts b/frontend/src/pages/full-encounter-demo/work-on-note.render.ts
index cf6450e..4e27cc6 100644
--- a/frontend/src/pages/full-encounter-demo/work-on-note.render.ts
+++ b/frontend/src/pages/full-encounter-demo/work-on-note.render.ts
@@ -66,7 +66,7 @@ export function markup(): string {
         <div class="bg-white rounded-xl border border-grey-200 p-5">
           <div class="flex items-center gap-2 mb-1">
             <h3 class="font-semibold text-grey-400">Normalize Data</h3>
-            <a href="${DOCUMENTATION_LINKS.generateNormalizedData}" target="_blank" rel="noopener" class="text-xs font-mono text-grey-250 hover:text-primary-600 bg-grey-100 hover:bg-primary-50 px-2 py-0.5 rounded transition-colors">POST /generate-normalized-data ↗</a>
+            <a href="${DOCUMENTATION_LINKS.generateNormalizedData}" target="_blank" rel="noopener" class="text-xs font-mono text-grey-250 hover:text-primary-600 bg-grey-100 hover:bg-primary-50 px-2 py-0.5 rounded transition-colors">POST /generate-normalized-data-async ↗</a>
           </div>
           <p class="text-xs text-grey-300 mb-4">Extract ICD-10 / LOINC codes in FHIR format from the note.</p>
           <button id="generate-normalized-btn" disabled class="bg-primary-600 hover:bg-primary-700 text-white text-sm font-medium px-4 py-2 rounded-lg transition-colors disabled:opacity-40 disabled:cursor-not-allowed">
diff --git a/frontend/src/shared/documentationLinks.ts b/frontend/src/shared/documentationLinks.ts
index 33273da..be843cf 100644
--- a/frontend/src/shared/documentationLinks.ts
+++ b/frontend/src/shared/documentationLinks.ts
@@ -3,6 +3,7 @@
 export const DOCUMENTATION_LINKS = {
   transcribeWs: "https://docs.nabla.com/user/transcribe-ws",
   generateNote: "https://docs.nabla.com/user/generate-note",
-  generateNormalizedData: "https://docs.nabla.com/user/generate-normalized-data",
+  generateNormalizedData:
+    "https://docs.nabla.com/user/generate-normalized-data-async",
   generatePatientInstructions: "https://docs.nabla.com/user/generate-patient-instructions",
 } as const;

From 7d43ecc7ba137d205a37c31f6734231ef2c507a4 Mon Sep 17 00:00:00 2001
From: Robin Nicollet <robin.nicollet@nabla.com>
Date: Thu, 16 Jul 2026 15:02:30 +0200
Subject: [PATCH 2/2] poll after 10 seconds, stop after 5 minutes

---
 frontend/src/api/async-job.ts | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/frontend/src/api/async-job.ts b/frontend/src/api/async-job.ts
index ecd2e42..cd432a1 100644
--- a/frontend/src/api/async-job.ts
+++ b/frontend/src/api/async-job.ts
@@ -6,15 +6,24 @@ export interface AsyncJob<TPayload = unknown> {
   payload?: TPayload;
 }
 
-const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_POLL_INTERVAL_MS = 10 * 1_000;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
 
 export async function pollUntilSucceeded<TPayload>(
   fetchJob: () => Promise<AsyncJob<TPayload>>,
-  options: { intervalMs?: number } = {},
+  options: { intervalMs?: number; timeoutMs?: number } = {},
 ): Promise<TPayload> {
   const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const deadline = Date.now() + timeoutMs;
 
   while (true) {
+    await sleep(intervalMs);
+
+    if (Date.now() >= deadline) {
+      throw new Error(`Did not get results within ${timeoutMs}ms. Aborting polling.`);
+    }
+
     const job = await fetchJob();
 
     if (job.status === "SUCCEEDED") {
@@ -27,7 +36,9 @@ export async function pollUntilSucceeded<TPayload>(
     if (job.status === "FAILED") {
       throw new Error(`Async job ${job.id} failed.`);
     }
-
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
   }
 }
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}