@aiqa/sdk 1.4.0 → 1.5.0-develop.1

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";
+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",
@@ -73,18 +73,111 @@ type ApplicationFactInput = {
     metadata?: Record<string, string>;
 };
 type QuestionStatus = "searching" | "asked" | "not_asked";
-type VerificationStatus = "processing" | "matched" | "unmatched";
+/**
+ * Per-fact verification state.
+ *
+ * Extended from the original three-state shape to carry progress signals
+ * the backend already detects but previously could not express. Consumers
+ * that switch on this value MUST treat unknown strings as "processing"
+ * (default fall-through) so older SDK builds keep working after the
+ * 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
+ *  - `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" | "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;
     question_asked?: boolean;
+    /**
+     * 0–1 (or 0–100 — scale matches the configured similarity method).
+     * Similarity between the agent's utterance and the expected question.
+     * Renamed from `match_score` to disambiguate from the answer-side score.
+     */
+    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). Undefined when no
+     * partial signal exists or for terminal results before this rolls out.
+     */
+    answer_match_score?: number;
     metadata?: Record<string, string>;
+    /**
+     * 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[];
+}
+/**
+ * Payload of the `FACT_VERIFIED` broadcast event.
+ *
+ * Fires on EVERY state transition the verification queue produces —
+ * 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) => {...});
+ *
+ * `addFact()`'s Promise resolves only on terminals; this event stream
+ * is the channel for rendering live progress in the agent UI.
+ */
+interface FactVerifiedPayload {
+    factId: string;
+    success: boolean;
+    verification_status?: VerificationStatus;
+    question_match_score?: number;
+    answer_match_score?: number;
+    matched_components?: string[];
+    missing_components?: string[];
+    /**
+     * Inner data payload. Shape matches `AddFactResult` (minus the
+     * top-level envelope fields) so consumers can reuse the same
+     * rendering code for the terminal addFact() resolution and the
+     * broadcast event.
+     */
+    data?: AddFactResult;
+    error?: string;
 }
 type FlagFactResult = {
     success: boolean;
@@ -136,4 +229,4 @@ declare class AiQaSdk implements IAiqaSdk {
     private isManagerEvent;
 }
 
-export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, FactAnswerFormatType, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type VerificationStatus };
+export { type AddFactResult, AiQaSdk, type Application, type ApplicationFact, type ApplicationFactAnswerChoice, type ApplicationFactAnswerFormat, type ApplicationFactInput, ConversationLanguage, FactAnswerFormatType, type FactVerifiedPayload, type FlagFactResult, IAiqaSdk, Methods, type QuestionStatus, type SdkError, type SdkEvent, type SetConversationLanguageResult, type SetConversationProductResult, type VerificationStatus };

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.3",
   main: "dist/node/node.js",
   module: "dist/node/node.js",
   types: "dist/node/node.d.ts",
@@ -3599,7 +3599,7 @@ var AiQaSdk = class {
           reject(parsed.error);
           return;
         }
-        resolve(parsed && parsed.data !== void 0 ? parsed.data : parsed);
+        resolve(parsed);
       };
       this.socket.on(requestId, handler);
       const payload = data && typeof data === "object" ? { ...data, requestId } : { requestId, data };
@@ -3629,7 +3629,23 @@ var AiQaSdk = class {
       is_skipped: fact.is_skipped ?? false
     };
     const result = await this.sendMessage("ADD_FACT" /* ADD_FACT */, payload);
-    return result && result.data !== void 0 ? result.data : result;
+    if (!result) return result;
+    const inner = result.data !== void 0 ? result.data : result;
+    const hasEnvelope = result.verification_status !== void 0 || result.matched_components !== void 0 || result.missing_components !== void 0;
+    if (!hasEnvelope || typeof inner !== "object" || inner === null) {
+      return inner;
+    }
+    const merged = { ...inner };
+    if (result.verification_status !== void 0) {
+      merged.verification_status = result.verification_status;
+    }
+    if (result.matched_components !== void 0) {
+      merged.matched_components = result.matched_components;
+    }
+    if (result.missing_components !== void 0) {
+      merged.missing_components = result.missing_components;
+    }
+    return merged;
   }
   async flagFact(factId) {
     const result = await this.sendMessage("FLAG_FACT" /* FLAG_FACT */, {