@aiqa/sdk 1.4.0-develop.2 → 1.4.0-develop.3

package/README.md

@@ -13,7 +13,11 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
   - [Recording Management](#recording-management)
   - [Fact Management](#fact-management)
   - [Event Handling](#event-handling)
+- [Verification lifecycle](#verification-lifecycle)
 - [Types](#types)
+  - [AddFactResult](#addfactresult)
+  - [VerificationStatus](#verificationstatus)
+  - [FactVerifiedPayload](#factverifiedpayload)
   - [FlagFactResult](#flagfactresult)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
@@ -130,7 +134,18 @@ console.log(result.success, result.language);
 
 #### `addFact(fact)`
 
-Adds a fact to the active application (Promise-based).
+Adds a fact to the active application and waits for the **terminal**
+verification verdict (Promise-based). The Promise resolves with an
+[`AddFactResult`](#addfactresult); subscribe to the
+[`FACT_VERIFIED`](#event-handling) broadcast event to render progress
+(`awaiting_question`, `awaiting_answer`, `partial`,
+`pending_confirmation_matched`, `pending_confirmation_unmatched`)
+while you wait.
+
+`addFact()` does not throw on verification failure — an unmatched
+fact resolves with `is_valid_answer: false` and (where the backend
+provides it) `verification_status: "unmatched"` or `"contradicted"`.
+Reject paths are reserved for transport / protocol errors.
 
 **Parameters:**
 
@@ -166,7 +181,7 @@ Adds a fact to the active application (Promise-based).
   ```
 
 ```typescript
-const isMatched = await sdk.addFact({
+const result = await sdk.addFact({
   id: "fact-123",
   questionId: "agreement-q",
   question: "Do you agree?",
@@ -174,6 +189,17 @@ const isMatched = await sdk.addFact({
   answer_format: { type: "STRING" },
   metadata: { uiFieldId: "policy-agreement", section: "consent" },
 });
+
+if (result.is_valid_answer) {
+  // verification_status will be "matched" (or "contradicted" if the
+  // customer explicitly contradicted the expected answer).
+  console.log("matched:", result.ai_answer);
+} else {
+  // verification_status will be "unmatched". matched_components /
+  // missing_components describe what the partial-match heuristics
+  // were able to extract.
+  console.log("unmatched:", result.missing_components);
+}
 ```
 
 ##### Question identity and `questionId`
@@ -278,6 +304,12 @@ Registers an event listener. Call `connect()` before `on()`.
 - `reconnect_failed` - Socket.IO reconnection failed
 - `authenticated` - Local event fired after successful authentication (provides Application object)
 - `app_version` - Server event with version requirements `{ min, max }`
+- `FACT_VERIFIED` - Broadcast event fired on **every** verification
+  state transition (both non-terminal progress and terminal verdicts)
+  for **every** fact in the active conversation. Payload shape:
+  [`FactVerifiedPayload`](#factverifiedpayload). Use this to render
+  live verification progress in your UI; `addFact()`'s Promise only
+  resolves on the terminal state.
 
 ```typescript
 sdk.connect();
@@ -288,7 +320,47 @@ sdk.on("connect", () => {
 sdk.on("authenticated", (application) => {
   console.log("Authenticated:", application);
 });
+
+sdk.on("FACT_VERIFIED", (payload) => {
+  // Renders progress for every fact in the conversation.
+  console.log(payload.factId, payload.verification_status);
+});
+```
+
+## Verification lifecycle
+
+A single `addFact()` call walks through a sequence of states emitted
+on the `FACT_VERIFIED` broadcast event before the Promise resolves:
+
 ```
+processing
+  └─> awaiting_question     (agent hasn't asked yet)
+        └─> awaiting_answer (asked, customer hasn't answered yet)
+              └─> partial   (partial evidence — e.g. "305" of "30521")
+                    └─> pending_confirmation_matched
+                          (backend has a match but is holding a settling
+                           window for mid-answer clarifications like
+                           spellings or "I mean…" corrections)
+                    └─> pending_confirmation_unmatched
+                          (same, but for a held unmatched verdict)
+                          │
+                          ▼
+                    matched | unmatched | contradicted   ← terminal
+```
+
+Rules for consumers:
+
+- **`addFact()` resolves only on a terminal state** (`matched`,
+  `unmatched`, `contradicted`). Render progress from the
+  `FACT_VERIFIED` event, render the final verdict from the Promise
+  result.
+- **Treat unknown `verification_status` strings as `processing`.**
+  The enum is additive — older SDK builds must fall through gracefully
+  when the backend ships a new state.
+- **`pending_confirmation_*` is never terminal.** The wire-visible
+  latency penalty is bounded by `settling_window_ms` on the server
+  (default 2000 ms). The held verdict can flip — that's the whole
+  point — so don't treat it as a commit.
 
 #### `off(eventName, callback?)`
 
@@ -321,11 +393,106 @@ Returned by `getFacts()`. Extends `ApplicationFactInput` and adds server-side fi
 type ApplicationFact = ApplicationFactInput & {
   ai_answer?: any;
   question_status: "searching" | "asked" | "not_asked";
-  verification_status: "processing" | "matched" | "unmatched";
+  verification_status: VerificationStatus;
+  flagged: boolean; // true once flagFact() has been called for this fact
   metadata: Record<string, string>; // always present; {} when not set on addFact
 };
 ```
 
+### AddFactResult
+
+Resolved value of `addFact()`. Only emitted at the terminal verification
+state — see [Verification lifecycle](#verification-lifecycle).
+
+```typescript
+interface AddFactResult {
+  /** Conversation the fact was attached to. */
+  conversation_id?: string;
+  /** Echo of the original question text from the fact input. */
+  question?: string;
+  /** Echo of the resolved answer_format.type (e.g. "STRING", "NUMBER"). */
+  answer_type?: string;
+
+  agent_answer?: string;
+  ai_answer?: string;
+  is_valid_answer: boolean;
+  question_asked?: boolean;
+
+  /**
+   * 0–1 (or 0–100 — scale matches the configured similarity method).
+   * Similarity between the agent's utterance and the expected question.
+   */
+  question_match_score?: number;
+
+  /**
+   * 0–1 score derived from how well the customer's answer matched expected.
+   * Populated by the verification queue from partial-match heuristics
+   * (numeric-prefix ratio, matched-components ratio).
+   */
+  answer_match_score?: number;
+
+  /**
+   * Top-level state at terminal resolution. Always one of `matched`,
+   * `unmatched`, or `contradicted` because the `addFact()` Promise only
+   * resolves on terminals. Optional during the rollout window for
+   * backwards compatibility with older backends.
+   */
+  verification_status?: VerificationStatus;
+
+  /**
+   * Per-fact partial-match breakdown carried through from the
+   * verification queue's component-wise comparators. For numeric-prefix
+   * facts these are `["prefix"]` / `["suffix"]`; future work will
+   * generalise to addresses, names, dates, etc.
+   */
+  matched_components?: string[];
+  missing_components?: string[];
+
+  metadata?: Record<string, string>;
+}
+```
+
+### VerificationStatus
+
+```typescript
+type VerificationStatus =
+  | "processing"
+  | "awaiting_question"
+  | "awaiting_answer"
+  | "partial"
+  | "pending_confirmation_matched"
+  | "pending_confirmation_unmatched"
+  | "matched"
+  | "unmatched"
+  | "contradicted";
+```
+
+The enum is additive: consumers that `switch` on this value MUST
+treat unknown strings as `"processing"` so older SDK builds keep
+working after the backend ships a new state. See the
+[Verification lifecycle](#verification-lifecycle) for the transitions
+and which states are terminal.
+
+### FactVerifiedPayload
+
+Payload of the `FACT_VERIFIED` broadcast event. Same shape as
+`AddFactResult` plus the `factId` / `success` / `error` envelope.
+
+```typescript
+interface FactVerifiedPayload {
+  factId: string;
+  success: boolean;
+  verification_status?: VerificationStatus;
+  question_match_score?: number;
+  answer_match_score?: number;
+  matched_components?: string[];
+  missing_components?: string[];
+  /** Same shape as AddFactResult so the same renderer handles both. */
+  data?: AddFactResult;
+  error?: string;
+}
+```
+
 ### ApplicationFactInput
 
 ```typescript
@@ -475,8 +642,16 @@ sdk.on("connect", async () => {
     await sdk.startRecording();
     console.log("Recording started");
 
-    // Add a fact
-    const factMatched = await sdk.addFact({
+    // Optional: render live verification progress for every fact
+    // in the conversation while the addFact() Promise is in flight.
+    sdk.on("FACT_VERIFIED", (payload) => {
+      console.log(
+        `[${payload.factId}] ${payload.verification_status ?? "processing"}`,
+      );
+    });
+
+    // Add a fact (Promise resolves at the terminal verdict)
+    const result = await sdk.addFact({
       id: "q1",
       question: "What is your name?",
       expected_answer: "",
@@ -485,7 +660,14 @@ sdk.on("connect", async () => {
       },
     });
 
-    console.log("Fact matched:", factMatched);
+    console.log(
+      "Terminal verdict:",
+      result.verification_status,
+      "is_valid_answer:",
+      result.is_valid_answer,
+      "ai_answer:",
+      result.ai_answer,
+    );
 
     // Stop recording
     await sdk.stopRecording();

package/dist/browser/browser.d.ts

@@ -32,7 +32,7 @@ declare enum ConversationLanguage {
     ES = "es",
     FR = "fr"
 }
-type SdkEvent = Methods | "connect" | "disconnect" | "close" | "error" | "reconnect_attempt" | "reconnect_error" | "reconnect_failed" | "authenticated" | "app_version" | "fact_verified";
+type SdkEvent = Methods | "connect" | "disconnect" | "close" | "error" | "reconnect_attempt" | "reconnect_error" | "reconnect_failed" | "authenticated" | "app_version" | "FACT_VERIFIED";
 declare enum FactAnswerFormatType {
     string = "STRING",
     number = "NUMBER",
@@ -83,21 +83,37 @@ type QuestionStatus = "searching" | "asked" | "not_asked";
  * backend starts emitting the additive states.
  *
  * Semantics:
- *  - `processing`        generic, just queued or transcription not ready
- *  - `awaiting_question` agent hasn't asked the question yet
- *  - `awaiting_answer`   question asked, customer hasn't answered yet
- *  - `partial`           partial evidence; backend still working on it
- *  - `matched`           terminal: answer matched expected
- *  - `unmatched`         terminal: budget exhausted with no match
- *  - `contradicted`      terminal (future): customer contradicted expected
+ *  - `processing`                     generic, just queued or transcription not ready
+ *  - `awaiting_question`              agent hasn't asked the question yet
+ *  - `awaiting_answer`                question asked, customer hasn't answered yet
+ *  - `partial`                        partial evidence; backend still working on it
+ *  - `pending_confirmation_matched`   backend has a matching answer but is
+ *                                     holding a settling window for mid-answer
+ *                                     clarifications (e.g. spellings, "I mean…");
+ *                                     resolves to `matched`/`unmatched`/`contradicted`
+ *  - `pending_confirmation_unmatched` same as above but the held verdict is
+ *                                     `unmatched`; UI can show "we heard X but it
+ *                                     doesn't match, waiting to confirm" instead
+ *                                     of a hard red verdict
+ *  - `matched`                        terminal: answer matched expected
+ *  - `unmatched`                      terminal: budget exhausted with no match
+ *  - `contradicted`                   terminal (future): customer contradicted expected
  */
-type VerificationStatus = "processing" | "awaiting_question" | "awaiting_answer" | "partial" | "matched" | "unmatched" | "contradicted";
+type VerificationStatus = "processing" | "awaiting_question" | "awaiting_answer" | "partial" | "pending_confirmation_matched" | "pending_confirmation_unmatched" | "matched" | "unmatched" | "contradicted";
 type ApplicationFact = ApplicationFactInput & {
     ai_answer?: any;
     question_status: QuestionStatus;
     verification_status: VerificationStatus;
+    /** True once `flagFact(factId)` has been called for this fact. */
+    flagged: boolean;
 };
 interface AddFactResult {
+    /** Conversation the fact was attached to. Useful for cross-fact correlation in agent UIs. */
+    conversation_id?: string;
+    /** Echo of the original question text from the fact input. */
+    question?: string;
+    /** Echo of the resolved `answer_format.type` (e.g. "STRING", "NUMBER", "SINGLE_CHOICE"). */
+    answer_type?: string;
     agent_answer?: string;
     ai_answer?: string;
     is_valid_answer: boolean;
@@ -133,14 +149,15 @@ interface AddFactResult {
     missing_components?: string[];
 }
 /**
- * Payload of the `fact_verified` broadcast event.
+ * Payload of the `FACT_VERIFIED` broadcast event.
  *
  * Fires on EVERY state transition the verification queue produces —
- * partial (`partial`, `awaiting_question`, `awaiting_answer`,
+ * non-terminal (`partial`, `awaiting_question`, `awaiting_answer`,
+ * `pending_confirmation_matched`, `pending_confirmation_unmatched`,
  * `processing`) AND terminal (`matched`, `unmatched`, `contradicted`).
  *
  * Subscribe with:
- *   sdk.on("fact_verified", (payload: FactVerifiedPayload) => {...});
+ *   sdk.on("FACT_VERIFIED", (payload: FactVerifiedPayload) => {...});
  *
  * `addFact()`'s Promise resolves only on terminals; this event stream
  * is the channel for rendering live progress in the agent UI.

package/dist/browser/browser.js

@@ -3396,7 +3396,7 @@ var compareVersions = (left, right) => {
 // package.json
 var package_default = {
   name: "@aiqa/sdk",
-  version: "1.4.0-develop.1",
+  version: "1.4.0-develop.2",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",