feat(core-api): add rapid order transcribe and parse endpoints

2026-02-27 11:12:32 -05:00
parent feb38c81fa
commit 7740ad4d2d
7 changed files with 808 additions and 12 deletions
--- a/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md
+++ b/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md
@@ -1,7 +1,7 @@
 # M4 Core API Frontend Guide (Dev)

 Status: Active  
-Last updated: 2026-02-24  
+Last updated: 2026-02-27  
 Audience: Web and mobile frontend developers

 ## 1) Base URLs (dev)
@@ -41,6 +41,16 @@ Authorization: Bearer <firebase-id-token>
 - `image/jpeg`
 - `image/jpg`
 - `image/png`
+- `audio/webm`
+- `audio/wav`
+- `audio/x-wav`
+- `audio/mpeg`
+- `audio/mp3`
+- `audio/mp4`
+- `audio/m4a`
+- `audio/aac`
+- `audio/ogg`
+- `audio/flac`
 6. Max upload size: `10 MB` (default)
 7. Current behavior: real upload to Cloud Storage (not mock)
 8. Success `200` example:
@@ -118,7 +128,91 @@ Authorization: Bearer <firebase-id-token>
 }
 ```

-## 4.4 Create verification job
+## 4.4 Rapid order transcribe (audio to text)
+1. Route: `POST /core/rapid-orders/transcribe`
+2. Auth: required
+3. Purpose: transcribe uploaded RAPID voice note into text for the RAPID input box.
+4. Request body:
+```json
+{
+  "audioFileUri": "gs://krow-workforce-dev-private/uploads/<uid>/rapid-request.webm",
+  "locale": "en-US",
+  "promptHints": ["server", "urgent"]
+}
+```
+5. Security checks:
+- `audioFileUri` must be in allowed bucket
+- `audioFileUri` path must be owned by caller (`uploads/<caller_uid>/...`)
+- file existence is required in non-mock upload mode
+6. Success `200` example:
+```json
+{
+  "transcript": "Need 2 servers ASAP for 4 hours.",
+  "confidence": 0.87,
+  "language": "en-US",
+  "warnings": [],
+  "model": "gemini-2.0-flash-001",
+  "latencyMs": 412,
+  "requestId": "uuid"
+}
+```
+7. Typical errors:
+- `400 VALIDATION_ERROR` (invalid payload)
+- `401 UNAUTHENTICATED` (missing/invalid bearer token)
+- `403 FORBIDDEN` (audio path not owned by caller)
+- `429 RATE_LIMITED` (model quota per user)
+- `502 MODEL_FAILED` (upstream model output/availability)
+
+## 4.5 Rapid order parse (text to structured draft)
+1. Route: `POST /core/rapid-orders/parse`
+2. Auth: required
+3. Purpose: convert RAPID text into structured one-time order draft JSON for form prefill.
+4. Request body:
+```json
+{
+  "text": "Need 2 servers ASAP for 4 hours",
+  "locale": "en-US",
+  "timezone": "America/New_York",
+  "now": "2026-02-27T12:00:00.000Z"
+}
+```
+5. Success `200` example:
+```json
+{
+  "parsed": {
+    "orderType": "ONE_TIME",
+    "isRapid": true,
+    "positions": [
+      { "role": "server", "count": 2 }
+    ],
+    "startAt": "2026-02-27T12:00:00.000Z",
+    "endAt": null,
+    "durationMinutes": 240,
+    "locationHint": null,
+    "notes": null,
+    "sourceText": "Need 2 servers ASAP for 4 hours"
+  },
+  "missingFields": [],
+  "warnings": [],
+  "confidence": {
+    "overall": 0.72,
+    "fields": {
+      "positions": 0.86,
+      "startAt": 0.9,
+      "durationMinutes": 0.88
+    }
+  },
+  "model": "gemini-2.0-flash-001",
+  "latencyMs": 531,
+  "requestId": "uuid"
+}
+```
+6. Contract notes:
+- unknown request keys are rejected (`400 VALIDATION_ERROR`)
+- when information is missing/ambiguous, backend returns `missingFields` and `warnings`
+- frontend should use output to prefill one-time order and request user confirmation where needed
+
+## 4.6 Create verification job
 1. Route: `POST /core/verifications`
 2. Auth: required
 3. Purpose: enqueue an async verification job for an uploaded file.
@@ -148,7 +242,7 @@ Authorization: Bearer <firebase-id-token>
 - `government_id`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).
 - `certification`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).

-## 4.5 Get verification status
+## 4.7 Get verification status
 1. Route: `GET /core/verifications/{verificationId}`
 2. Auth: required
 3. Purpose: polling status from frontend.
@@ -163,7 +257,7 @@ Authorization: Bearer <firebase-id-token>
 }
 ```

-## 4.6 Review verification
+## 4.8 Review verification
 1. Route: `POST /core/verifications/{verificationId}/review`
 2. Auth: required
 3. Purpose: final human decision for the verification.
@@ -188,7 +282,7 @@ Authorization: Bearer <firebase-id-token>
 }
 ```

-## 4.7 Retry verification
+## 4.9 Retry verification
 1. Route: `POST /core/verifications/{verificationId}/retry`
 2. Auth: required
 3. Purpose: requeue verification to run again.
@@ -234,6 +328,42 @@ const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/invo
 const data = await res.json();
 ```

+## 5.3 Rapid audio transcribe request
+```ts
+const token = await firebaseAuth.currentUser?.getIdToken();
+const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/rapid-orders/transcribe', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    audioFileUri: 'gs://krow-workforce-dev-private/uploads/<uid>/rapid-request.webm',
+    locale: 'en-US',
+    promptHints: ['server', 'urgent'],
+  }),
+});
+const data = await res.json();
+```
+
+## 5.4 Rapid text parse request
+```ts
+const token = await firebaseAuth.currentUser?.getIdToken();
+const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/rapid-orders/parse', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    text: 'Need 2 servers ASAP for 4 hours',
+    locale: 'en-US',
+    timezone: 'America/New_York',
+  }),
+});
+const data = await res.json();
+```
+
 ## 6) Notes for frontend team
 1. Use canonical `/core/*` routes for new work.
 2. Aliases exist only for migration compatibility.